Skip to main content

Get and display a Specification

Status: Implemented

Use a public Specification when your application needs a stable reference to completed canonical demand after interpretation has finished.

completed canonical GJS
  -> POST /v1/specifications
  -> stable specification_id
  -> GET /v1/specifications/{specification_id}
  -> display or reuse the retained canonical demand

Interpretation does not persist a Specification automatically. Retention is an explicit developer action.

Retain the GJS you already received​

This guide assumes gjs.json came directly from the Understand a print requirement journey.

Build the retention request around that returned GJS rather than copying the GJS schema into your application:

jq -n \
  --slurpfile gjs gjs.json \
  '{
    gjs: $gjs[0],
    idempotency_key: "campaign-4821-v1",
    external_references: [
      {system: "workflow", reference: "campaign-4821"}
    ]
  }' > create-specification.json

Retain it:

curl https://api.gnaww.io/v1/specifications \
  --request POST \
  --header "X-Gnaww-API-Key: ${GNAWW_API_KEY}" \
  --header "Content-Type: application/json" \
  --dump-header specification-create-headers.txt \
  --output created-specification.json \
  --data @create-specification.json

A successful create response wraps the immutable resource in specification. Store the returned identifier:

export SPECIFICATION_ID="$(jq -r '.specification.specification_id' created-specification.json)"

Use a stable idempotency key when retrying the same retention request. Reusing that key with different resource input is a conflict rather than a request to mutate the existing Specification.

Retrieve it later​

curl "https://api.gnaww.io/v1/specifications/${SPECIFICATION_ID}" \
  --header "X-Gnaww-API-Key: ${GNAWW_API_KEY}" \
  --dump-header specification-read-headers.txt \
  --output specification.json

The GET response is the safe Specification resource itself. Its gjs field is the retained canonical demand:

jq '{
  specification_id,
  gjs_schema_version,
  recipe,
  gjs
}' specification.json

For a user-facing view, display the controlled GJS fields that are relevant to the workflow and keep specification_id as the durable resource reference. Do not treat content_fingerprint_sha256 as another business identifier.

Specification ID is not Recipe ID​

specification_id answers:

Which retained canonical demand resource is this?

Recipe ID answers:

Which exact physical manufacturing definition is this?

Two separate Specifications can therefore expose the same eligible Recipe ID. Creating a Specification does not persist a Recipe as a side effect.

Isolation and safe errors​

Specification reads are tenant and workspace scoped. Unknown and inaccessible resources both return the same safe 404 specification_not_found response.

Retain the X-Request-Id and X-Correlation-Id headers for troubleshooting, but do not log credentials or sensitive source payloads.

What this does not do​

A durable Specification does not select a producer and does not confirm:

  • current price;
  • current availability or capacity;
  • producer acceptance;
  • a quote;
  • an order;
  • production or dispatch state.

The detailed resource semantics live in Specifications. The generated API reference remains the request and response schema authority.

Next​

Continue with the retained gjs to Find capable production.

Last updated on