> 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/issue-with-a-registered-schema.md).

# Issue with a registered schema

What changes on POST /commerce/srrs when metadata.$schema points at a registered schema — validation, file URLs, limits, error naming.

<mark style="color:green;">`POST`</mark> `<base_url>/port/api/v1/commerce/srrs`

Same route, headers, body envelope and response as [Issue & Transfer](https://docs.startrail.io/issue-transfer-api/issue-and-transfer-srr-nft/issue-and-transfer.md). An entry whose `metadata.$schema` is a registered schema (any of the [three forms](https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas.md#the-three-forms-of-the-schema-reference)) is treated as below; entries on the official schema keep the existing rules. The two kinds can be mixed in one `payload`.

## What changes per entry

| Concern                                   | Official schema                                                                               | Registered schema                                                                                                                                                                                |
| ----------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Validation                                | common-js, as sent                                                                            | Against the latest published version of the schema, in the pinned form (after storage URLs became `ipfs://<cid>`)                                                                                |
| Version                                   | Converted to the latest official version                                                      | Moved to the latest published version of the lineage; refused if not valid against it                                                                                                            |
| `name` / `image` / `description` defaults | Filled in when absent                                                                         | Nothing is added or changed; your document is validated as it is                                                                                                                                 |
| `isDigital` → `digitalComponents`         | Auto-initialised                                                                              | Not touched                                                                                                                                                                                      |
| `attachmentFiles`                         | Folded into `metadata.digitalComponents` / `metadata.attachmentFiles`                         | **Refused** (`400`) — the fold would add keys your schema may not allow                                                                                                                          |
| `externalUrls`                            | First entry becomes `metadata.external_url`                                                   | Ignored; put links in a field of your own schema                                                                                                                                                 |
| File URLs                                 | Only `thumbnailURL`, `image`, `contractTerms.fileURL` are file fields; external hosts refused | **Any string value** that is the `finalUrl` of a file in Startbahn storage (public category) is stored as `ipfs://<cid>`, whatever the field is called. URLs on other hosts are kept as they are |
| Size                                      | ≤ 204800 bytes serialized                                                                     | Same                                                                                                                                                                                             |
| Where errors are raised                   | gogh-api                                                                                      | gogh-api for the request checks; schema errors come from the convert step and are passed on as `400`                                                                                             |

{% hint style="warning" %}
**Send storage URLs, not gateway URLs, for files.** A `finalUrl` from [`/commerce/signedUrls`](https://docs.startrail.io/issue-transfer-api/issue-and-transfer-srr-nft/request-signed-url-for-upload-download-files.md) is replaced by `ipfs://<cid>` before validation, so a field your schema restricts to `^ipfs://` can be sent as the storage URL. The file must exist and its CID must be ready (poll [`/commerce/fileMetadata`](https://docs.startrail.io/issue-transfer-api/issue-and-transfer-srr-nft/file-information-metadata.md)); otherwise the entry is refused — see [storage URL for a missing file](https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/errors-limits-and-edge-cases.md#edge-cases). A `https://cdn.startrail.io/ipfs/<cid>` URL is not a storage URL: it is kept as it is and only passes if your schema allows it.
{% endhint %}

{% hint style="danger" %}
**`$schema` must be one of the three forms.** A gateway URL such as `https://cdn.startrail.io/ipfs/<cid>` as `$schema` is neither a registered reference nor an official one and is refused with `$schema path is invalid, file is not found`.
{% endhint %}

## Order of checks

All checks run on the whole payload before anything is signed; the first failure refuses the whole request and nothing is issued.

| #  | Check                                                                | Names the entry as                                              | Where                                              |
| -- | -------------------------------------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------- |
| 1  | Headers                                                              | —                                                               | `401`                                              |
| 2  | Every entry has `metadata`                                           | —                                                               | `400` `Some of the metadata is not defined`        |
| 3  | DTO: field types, `$schema` names a published schema                 | `payload.<index>.<field>`                                       | `400`, array of messages                           |
| 4  | Each `metadata` ≤ 204800 bytes                                       | `payload[<index>]`                                              | `400`                                              |
| 5  | No `attachmentFiles` on a registered-schema entry                    | `(externalId <externalId>)`                                     | `400`                                              |
| 6  | File URLs of official-schema entries                                 | `[<externalId>] <field>: <url>`                                 | `400`                                              |
| 7  | `issuer-address` and every `artistAddress` are LUWs                  | —                                                               | `400` `Address not found: …`                       |
| 8  | Convert step (validation in the pinned form, storage files, version) | `metadataBatch[<index>]` when the batch has more than one entry | `400` `Some metadata is failed to be converted: …` |
| 9  | Request log: `requestId` and content replay                          | —                                                               | `400`                                              |
| 10 | Typed data: closed-release wallet check, quota, duplicates           | `txs[<index>]` (bulk)                                           | `403` / `400` passed through                       |
| 11 | Signing and execution                                                | —                                                               | `201`, or `500`                                    |

The convert step runs in chunks of 100 entries; the index in `metadataBatch[<index>]` is the position in your `payload`, not in the chunk.

## Request

```json
{
  "requestId": "ingot-2026-10-27-001",
  "payload": [
    {
      "externalId": "ingot-2026-10-27-001-1",
      "collectionAddress": "0x8B116A8896538377328936279E64B11303cBf7B1",
      "artistAddress": "0xA6E6a9E20a541680a1D6E1412f5088AefBF58a22",
      "isPrimaryIssuer": true,
      "lockExternalTransfer": false,
      "metadata": {
        "$schema": "https://api.startrail.io/api/v1/schema/ingot-registry-record.latest.schema.json",
        "name": "Gold bar 1 kg, serial HPM-2024-017345",
        "identifierScheme": "ingot-markings-v1",
        "itemIdentifier": "8b9e62a876ca2a6a329fb54ae575e34d11ecd2b46cb7d892a76c2d8d0c161141",
        "imageHash": "0c405ae068a7d62aef5050ab719466dab62a6a4a7458a5e16eb6ff7c30c7888c",
        "hubEventId": "ee95c503193e01622328ca533de302baf972f0cfab74f7777478554ee675029b",
        "markings": {
          "metal": "gold",
          "refiner": "Helvetia Precious Metals",
          "serialNumber": "HPM-2024-017345",
          "fineness": 0.9999,
          "weight": { "value": 1000, "unit": "g" },
          "form": "bar",
          "yearOfManufacture": 2024
        },
        "custody": {
          "custodian": { "externalId": "CUST-001", "name": { "en": "Northern Vault Services AG" } },
          "facility": "ZRH-V2",
          "country": "CH",
          "status": "in_custody",
          "since": "2026-01-15T09:00:00+01:00"
        }
      }
    }
  ]
}
```

The fields are those of the example schema used throughout this section; your schema defines its own. `artistAddress` is required by the route whatever the schema; for records that have no artist use the issuer LUW.

## Response

`201` with the same shape as the official route. `metadataCID` is the CID of the pinned document (`$schema` rewritten to `ipfs://<cid>` of the latest version, storage URLs rewritten to `ipfs://<cid>`), so it differs from a CID you compute over the document you sent — use [`POST /commerce/metadata`](https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/pin-metadata.md) to get it beforehand.

```json
{
  "results": [
    {
      "status": "waiting_for_mining",
      "srr": {
        "tokenId": "561308332886",
        "metadataCID": "bafkreic6dylmir5h25qds7jpqxuai5m556kdzd3jwgcf6m7m65bv32rery",
        "metadataURL": "https://cdn.startrail.io/ipfs/bafkreic6dylmir5h25qds7jpqxuai5m556kdzd3jwgcf6m7m65bv32rery",
        "collectionContractAddress": "0x8B116A8896538377328936279E64B11303cBf7B1"
      },
      "externalId": "ingot-2026-10-27-001-1"
    }
  ]
}
```

`201` means accepted, not mined. Confirm through the [webhook](https://docs.startrail.io/issue-transfer-api/issue-and-transfer-srr-nft/webhook-setup.md) or by polling the read route until `metadataDigest` equals `metadataCID` — see [subgraph lag](https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/errors-limits-and-edge-cases.md#edge-cases).

## Errors specific to registered schemas

| Status | Message                                                                                                                                                                              | When                                                                                                                                 |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | `payload.<i>.metadata is invalid. Check it against the metadata JSON schema. Details: $schema path is invalid, cid is not found ({}).`                                               | `$schema` is `ipfs://<cid>` but no published schema has that CID                                                                     |
| `400`  | `payload.<i>.metadata is invalid. Check it against the metadata JSON schema. Details: $schema path is invalid, file is not found ({}).`                                              | `$schema` is a name form with no published version, a gateway URL, or any other unknown URL                                          |
| `400`  | `payload[<i>]: metadata exceeds the maximum size of 204800 bytes (serialized size: <n> bytes)`                                                                                       | One entry is too large                                                                                                               |
| `400`  | `attachmentFiles is not supported for metadata on a registry schema (externalId <externalId>)`                                                                                       | `attachmentFiles` given on a registered-schema entry                                                                                 |
| `400`  | `Some metadata is failed to be converted: metadata failed validation against JSON schema. Details: <path> <message> (<params>). …`                                                   | The document breaks the schema (in its pinned form, against the latest version)                                                      |
| `400`  | `Some metadata is failed to be converted: metadataBatch[<i>]: metadata failed validation against JSON schema. Details: …`                                                            | Same, in a payload with more than one entry                                                                                          |
| `400`  | `… Details: refers to a file that is not in storage ({"url":"<url>"}).`                                                                                                              | A storage URL whose file was never uploaded                                                                                          |
| `400`  | `… Details: refers to a file whose CID is not calculated yet, retry shortly ({"url":"<url>"}).`                                                                                      | Uploaded, CID still computing                                                                                                        |
| `400`  | `… Details: /$schema names v<old> of <name>; an SRR is issued on the latest version, v<latest>, and the metadata is not valid against it ({"named":"<old>","latest":"<latest>"}). …` | `$schema` names an older version and the document does not fit the latest one; the remaining details are the latest version's errors |
| `403`  | `Licensed user <issuer-address> is not enabled for registered metadata schemas`                                                                                                      | Closed release, wallet not enabled — [contact Startbahn](https://startbahn.io/contact)                                               |
| `500`  | `schema registry resolution failed`                                                                                                                                                  | The registry could not be read; retry                                                                                                |

The full catalogue, including everything shared with the official route, is in [Errors, limits and edge cases](https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/errors-limits-and-edge-cases.md#post-commerce-srrs).


---

# 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/issue-with-a-registered-schema.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.
