Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

🧩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.

Replace <base_url> with the environment you are calling — see URL per environment. 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. The schema registry routes are public.

Pages

Page
What it covers

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

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.

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, 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.

Last updated

Was this helpful?