🧩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 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.
Pages
What changes on POST /commerce/srrs when metadata.$schema is a registered schema
POST /commerce/metadata — pin a document and get its CID without issuing
PUT and PATCH /commerce/srrs/{tokenId}/metadata — replace or patch the document of an issued SRR
POST /commerce/srrs/transfers, claim and cancel
The four public GET /schema-registry/... routes
Every error, every limit, per route
Collection → issue → read → update → transfer → viewer link, end to end
Concepts
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
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.
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.
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:
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 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. Private schemas are not listed by search but resolve by CID (possession of the CID is the capability).
What stays the same
Headers,
requestIdidempotency,collectionAddress,to, webhooks and the subgraph read-back work as for the official schema.metadata.$schemaon the official schema keeps its behaviour; registered and official metadata can be mixed in onePOST /commerce/srrspayload.
Last updated
Was this helpful?