The Public Catalog API

SDCStudio publishes a read-only HTTP API for the components, data models, schemas and ontologies that have been published in public projects. It is mounted at /api/v1/catalog/ on the production host, https://sdcstudio.axius-sdc.com. No account is needed to call it. The in-app Components page requires a sign-in, and the web application has no catalog page of its own: the API is the public catalog.

Every endpoint answers GET only. Responses are JSON; a browser without a JSON Accept header receives the browsable HTML form, and ?format=json forces JSON there. Anonymous callers are limited to 200 requests per hour on the listing endpoints. A caller that sends an API key as Authorization: Token sdcs_... (see api-keys.md) is limited to 2,000 per hour instead. Artifact and ontology downloads have their own anonymous limit of 60 per hour.

What is listed

The component listing returns components that are both published and public, across every component type SDCStudio models: XdString, XdBoolean, XdCount, XdQuantity, XdFloat, XdDouble, XdOrdinal, XdTemporal, XdLink, XdFile, XdToken, Cluster, Units, Party, Participation, Audit, Attestation, XdInterval, ReferenceRange, SimpleReferenceRange, and the eight list types (XdBooleanList, XdDecimalList, XdDoubleList, XdIntegerList, XdNonNegativeIntegerList, XdPositiveIntegerList, XdStringList, XdTokenList). Retired components are left out unless you ask for them.

The data model listing returns published models whose project is public. The schema route under /dmlib/ is different: any published model resolves there, whatever its project's visibility, because knowing the model's identifier is the capability.

SDCStudio hosts nineteen public library projects. Their names and contents are described at https://semanticdatacharter.com/vocabularies/ and in ../getting-started/public-libraries.md. The project parameter below takes a project's exact name (matched without regard to case), not an id. Production names include FHIR, NIH_CDE, UN-EDIFACT, NIH_PhenX, Human Resources, FOCUS, Business Documents and Default; spaces are URL-encoded as %20.

Endpoints

Components

Query parameters:

• project: a public project's exact name.
• search: text matched against label and description.
• type: one component type name, for example XdQuantity or Cluster, matched without regard to case (xdquantity works). An unknown type returns {"count": 0, "results": []}.
• page: 1-based page number, default 1.
• page_size: default 50, maximum 200.
• include_retired: 1, true or yes to list retired components as well.

Results are ordered by label across all types.

curl -s "https://sdcstudio.axius-sdc.com/api/v1/catalog/components/?project=Default&page_size=2"

{
  "count": 111,
  "page": 1,
  "page_size": 2,
  "results": [
    {
      "ct_id": "iv6bvlkxjcgzvyl1ck6n8tgo",
      "label": "Active Indicator",
      "description": "Whether the thing described is currently active. ...",
      "component_type": "XdBoolean",
      "project_name": "Default",
      "reuse_ref": "@Default:Active Indicator",
      "units": "",
      "retired": false,
      "retired_at": null,
      "superseded_by": null
    },
    { "ct_id": "ncxxt7wgs7soxw7kbmapxvg3", "label": "Address (Line 1)", "...": "..." }
  ]
}

Each result carries the component's identifier, label, description, type, project name, a reuse_ref of the form @Project:Label, and its retirement state. units is the units label for XdCount, XdQuantity, XdFloat and XdDouble, the units text stored on the numeric list types, and an empty string otherwise. superseded_by is filled only for a retired component that has a successor. Semantic links are not exposed on this endpoint.

curl -s "https://sdcstudio.axius-sdc.com/api/v1/catalog/components/?project=Business%20Documents&type=XdQuantity&page_size=1"
curl -s "https://sdcstudio.axius-sdc.com/api/v1/catalog/components/?project=Human%20Resources&type=XdStringList"
curl -s "https://sdcstudio.axius-sdc.com/api/v1/catalog/components/?search=currency&page_size=10"
curl -s "https://sdcstudio.axius-sdc.com/api/v1/catalog/components/?project=NIH_CDE&page=2&page_size=100"

The first of these returns an XdQuantity whose units is "Currency"; the second returns a Human Resources string list.

Bringing a public component into your project

The catalog is a browse surface. To use a public component in your own work, open it in the application and use Copy: it makes an unpublished copy, labeled COPY -- ..., in a project you choose, with lineage to the source. Copy is refused when the source is retired. See copy-and-retire.md.

Data models

GET /api/v1/catalog/dms/ takes project, search (matched against title and description), page and page_size (default 50, maximum 200), and answers count, page, page_size and results, ordered by title. Each entry has ct_id, identifier (the dm- form), title, description, project_name, about, created and updated.

curl -s "https://sdcstudio.axius-sdc.com/api/v1/catalog/dms/?project=Business%20Documents"
curl -s "https://sdcstudio.axius-sdc.com/api/v1/catalog/dms/?project=UN-EDIFACT"
curl -s "https://sdcstudio.axius-sdc.com/api/v1/catalog/dms/?project=NIH_PhenX"

GET /api/v1/catalog/dm/<ct_id>/ returns the same fields plus artifacts, a map from artifact type to its download route, listing only the artifacts that have been generated, and components, a flat list of every component in the model's cluster tree, each with name, type, ct_id and parent_cluster. A model that is not published, or whose project is not public, answers 404 with {"detail": "No DM matches the given query."}.

curl -s "https://sdcstudio.axius-sdc.com/api/v1/catalog/dm/jkuyr38hydqaiwlq5vhp2rjr/"

{
  "ct_id": "jkuyr38hydqaiwlq5vhp2rjr",
  "identifier": "dm-jkuyr38hydqaiwlq5vhp2rjr",
  "title": "Credit Note",
  "project_name": "Business Documents",
  "artifacts": {
    "xsd": "/api/v1/catalog/dm/jkuyr38hydqaiwlq5vhp2rjr/xsd/",
    "jsonld": "/api/v1/catalog/dm/jkuyr38hydqaiwlq5vhp2rjr/jsonld/",
    "...": "..."
  },
  "components": [
    { "name": "Audit Agent Reference", "type": "XdString", "ct_id": "dkc2ccj5te35z9gd4bu1blcq", "parent_cluster": "t2tvd3wylxrstdeu5aw6gkw1" }
  ]
}

Artifacts

GET /api/v1/catalog/dm/<ct_id>/<artifact>/ serves one generated artifact. The artifact types are xsd, xml, json, jsonld, html, sha1, zip, ttl, shacl and gql. The xml and json artifacts are the XML and JSON Governed Data Record instances generated with the model (see generating-outputs.md).

On production, where artifacts live in cloud storage, the response is a JSON pointer rather than the file:

curl -s "https://sdcstudio.axius-sdc.com/api/v1/catalog/dm/jkuyr38hydqaiwlq5vhp2rjr/xsd/"

{
  "download_url": "https://storage.googleapis.com/.../dm-jkuyr38hydqaiwlq5vhp2rjr.xsd",
  "filename": "dm-jkuyr38hydqaiwlq5vhp2rjr.xsd",
  "storage": "gcs"
}

Follow download_url to fetch the bytes. A self-hosted SDCStudio on local storage streams the file directly with an immutable Cache-Control header. An unknown artifact type answers 404 with {"error": "Unknown artifact type '...'"}; an artifact that has not been generated for the model answers 404 with an error saying so.

Ontologies

GET /api/v1/catalog/ontologies/ lists the SDC4 reference ontologies: sdc4 (base type definitions) and sdc4-meta (metadata predicates), each with name, content_type and description. GET /api/v1/catalog/ontologies/<name>/ returns the Turtle file with an immutable Cache-Control header; an unknown name answers 404.

curl -s "https://sdcstudio.axius-sdc.com/api/v1/catalog/ontologies/"
curl -sO "https://sdcstudio.axius-sdc.com/api/v1/catalog/ontologies/sdc4/"

Schema resolution under /dmlib/

Every generated Governed Data Record, and every Settlement Receipt, names its schema as https://semanticdatacharter.com/dmlib/dm-<ct_id>.xsd. A holder of the SDC4 library resolves that identifier offline through the shipped XML catalog, which rewrites the prefix to a local directory. Everyone else resolves it on the network with the same path shape on this host, so an XML catalog can equally rewrite the prefix to https://sdcstudio.axius-sdc.com/dmlib/.

curl -s "https://sdcstudio.axius-sdc.com/dmlib/dm-jkuyr38hydqaiwlq5vhp2rjr.xsd" -o dm-jkuyr38hydqaiwlq5vhp2rjr.xsd
curl -s "https://sdcstudio.axius-sdc.com/dmlib/dm-jkuyr38hydqaiwlq5vhp2rjr.versions.json"

The .xsd route returns the stored schema bytes exactly, as application/xml, with Cache-Control: public, max-age=31536000, immutable and an ETag derived from the SHA-256 of the body, so hashing what you receive reproduces the schema_hash a Receipt carries. Adding ?sha256=<hex> returns the archived bytes of that one version, or 404 if the model never served that hash. /dmlib/by-hash/<sha256>.xsd serves a version by its hash alone.

versions.json returns the identifier as schema_url, the current_sha256, and a versions array, newest first, each with sha256, size, archived_at, current and the url that serves it:

{
  "schema_url": "https://semanticdatacharter.com/dmlib/dm-jkuyr38hydqaiwlq5vhp2rjr.xsd",
  "current_sha256": "29f7948826d3380b5cacebc767c16a3012c7cadfd78ce79db690035adfd5ef2a",
  "versions": [
    { "sha256": "29f79488...", "size": 1484163, "archived_at": "...", "current": true, "url": "https://sdcstudio.axius-sdc.com/dmlib/dm-jkuyr38hydqaiwlq5vhp2rjr.xsd?sha256=29f79488..." }
  ]
}

An unpublished model does not exist on these routes: both answer 404, never 403, so the response does not reveal whether a draft with that id exists. Anonymous schema resolution is limited to 600 requests per hour. How a Receipt uses these routes is described in verifiable-settlement.md.

Errors at a glance