> For the complete documentation index, see [llms.txt](https://docs.startrail.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas.md).

# Flexible metadata (registered schemas)

Issue, update and transfer SRRs whose metadata follows a JSON Schema of your own, registered with Startrail — concepts, the $schema forms, the closed release.

The Commerce API can issue SRRs whose metadata does not follow the official [SRR metadata schema](https://docs.startrail.io/metadata-schema/startrail-registry-srr.md) but a **registered schema**: a JSON Schema document that Startbahn registers for you in the public schema registry. Your metadata is validated against that schema, pinned to IPFS and put on chain like any other SRR.

{% hint style="info" %}
Replace `<base_url>` with the environment you are calling — see [URL per environment](https://docs.startrail.io/readme/url-per-environment.md). All commerce routes below are mounted under `<base_url>/port/api/v1/` and take the headers `commerce-api-key` and `issuer-address` described in [Issue & Transfer SRR](https://docs.startrail.io/issue-transfer-api/issue-and-transfer-srr-nft.md#required-headers). The schema registry routes are public.
{% endhint %}

## Pages

| Page                                                                                                                                                  | What it covers                                                                                       |
| ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| [Issue with a registered schema](https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/issue-with-a-registered-schema.md) | What changes on `POST /commerce/srrs` when `metadata.$schema` is a registered schema                 |
| [Pin metadata](https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/pin-metadata.md)                                     | `POST /commerce/metadata` — pin a document and get its CID without issuing                           |
| [Update metadata](https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/update-metadata.md)                               | `PUT` and `PATCH /commerce/srrs/{tokenId}/metadata` — replace or patch the document of an issued SRR |
| [Transfers](https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/transfers.md)                                           | `POST /commerce/srrs/transfers`, claim and cancel                                                    |
| [Schema registry](https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/schema-registry.md)                               | The four public `GET /schema-registry/...` routes                                                    |
| [Errors, limits and edge cases](https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/errors-limits-and-edge-cases.md)    | Every error, every limit, per route                                                                  |
| [Worked example](https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/worked-example.md)                                 | Collection → issue → read → update → transfer → viewer link, end to end                              |

## Concepts

| Term              | Meaning                                                                                                                                                                                                               |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Registered schema | A JSON Schema document (draft-07 or 2020-12) stored in the schema registry, identified by its IPFS CID and by a lineage `name` plus a `version`. Registration is done by Startbahn; you receive the CID and the name. |
| Lineage           | All versions of one schema name. Exactly one published version is the **latest**.                                                                                                                                     |
| Published         | Only a published version resolves on the public routes and can be used in metadata.                                                                                                                                   |
| Pinned form       | The document as it is stored on IPFS and referenced on chain: `$schema` as `ipfs://<cid>`, file URLs as `ipfs://<cid>`, keys in canonical order.                                                                      |

## The three forms of the schema reference

| Form             | Example                                                                                                                                                         | Resolves to                                                        |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| CID              | `ipfs://bafkrei…`                                                                                                                                               | That exact schema document                                         |
| Name and version | `https://api.startrail.io/api/v1/schema/ingot-registry-record.v0.3.schema.json`                                                                                 | The published version `0.3` of the lineage `ingot-registry-record` |
| Name, latest     | `https://api.startrail.io/api/v1/schema/ingot-registry-record.latest.schema.json` or `https://api.startrail.io/api/v1/schema/ingot-registry-record.schema.json` | The latest published version of the lineage                        |

Only the path `/api/v1/schema/<file>` of the name forms is read; the host is not checked. The name `registry-record-metadata` is the official schema and cannot name a registered one.

{% hint style="warning" %}
**What goes on chain is always the CID form.** Whatever form you send, the pinned document carries `$schema: "ipfs://<cid>"`. A name reference is resolved at the time of the request and never floats to a later version after the CID is on chain.
{% endhint %}

## Issuance lands on the latest published version

An SRR is always issued on the **latest published version** of its schema. If `$schema` names an older version (by CID or by name) the metadata is validated against the latest version and leaves with the latest version's CID. If it is not valid against the latest version the request is refused with `400` — see [older schema version moved to latest](https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/errors-limits-and-edge-cases.md#edge-cases).

Updates of an existing SRR (`PUT` / `PATCH`) do **not** move: the document stays on the version its `$schema` names, unless a `PATCH` sets `payload.schema`.

## Closed release

Registered schemas are in a closed release. While it is on, an issuer wallet must be enabled for them; otherwise issuance and metadata updates on a registered schema are refused with:

```json
{ "statusCode": 403, "message": "Licensed user 0xA6E6a9E20a541680a1D6E1412f5088AefBF58a22 is not enabled for registered metadata schemas" }
```

The check is on the LUW named by `issuer-address`, after the document was validated (an invalid document keeps its `400`). Metadata on the official schema is never affected. To get a wallet enabled, [contact Startbahn](https://startbahn.io/contact) with the LUW address and the environment.

## Public registry

Anyone can search public published schemas, read a schema record and its document by CID, and resolve a name to its published versions — see [Schema registry](https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/schema-registry.md). Private schemas are not listed by search but resolve by CID (possession of the CID is the capability).

## What stays the same

* Headers, `requestId` idempotency, `collectionAddress`, `to`, webhooks and the subgraph read-back work as for the official schema.
* `metadata.$schema` on the official schema keeps its behaviour; registered and official metadata can be mixed in one `POST /commerce/srrs` payload.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
