Skip to content

API Publication and Conformance

Source version 1.2.0. Draft for discussion and validation.

Publication package

A complete API profile package should contain:

api-publication-package/
├── openapi.yaml
├── overlays/
│   ├── semantic.overlay.yaml
│   ├── trust.overlay.yaml
│   └── agent-safety.overlay.yaml
├── schemas/
│   ├── request.schema.json
│   ├── response.schema.json
│   └── problem.schema.json
├── contexts/
│   └── api-context-1.0.0.jsonld
├── shapes/
│   └── response.shacl.ttl
├── workflows/
│   └── outcome.arazzo.yaml
├── mcp/
│   ├── projection-manifest.json
│   ├── tools.json
│   └── resources.json
├── a2a/
│   └── agent-card.json
├── examples/
│   ├── valid-request.json
│   ├── valid-response.jsonld
│   └── invalid-request.json
├── provenance/
│   └── publication-prov.jsonld
├── tests/
│   ├── openapi-conformance/
│   ├── json-schema/
│   ├── json-ld/
│   ├── mcp-equivalence/
│   └── security/
└── manifest.jsonld

Only artefacts applicable to the API need be present, but every omission must be justified by the declared conformance class.

Conformance requirements

A publication claiming conformance to the GS1 GenAI-Enabled API Semantic Publication Profile must pass:

  1. OpenAPI structural and profile-rule validation.
  2. JSON Schema validation for all examples.
  3. JSON-LD context syntax, expansion and semantic-mapping tests.
  4. Referential-integrity tests for external schemas, contexts and profile identifiers.
  5. Operation-description quality checks.
  6. Effect, idempotency, confirmation and data-classification completeness checks.
  7. Security-scheme and scope validation.
  8. Error-schema and retry-behaviour tests.
  9. Deterministic MCP projection and schema-equivalence tests where MCP is claimed.
  10. Arazzo workflow resolution tests where workflows are claimed.
  11. A2A Agent Card and skill-reference tests where A2A is claimed.
  12. Provenance, versioning, integrity and deprecation tests.
  13. Positive, negative, misuse and prompt-injection test cases.
  14. Human review for operations with material side effects.

Profile test question

Can an unfamiliar authorised AI system determine what this API does, when it should and should not use each operation, what every input and output means, which authority and standards support the result, what effects and risks invocation creates, how to recover from failure, and how to generate an equivalent MCP tool or resource without inventing missing semantics?

If any answer depends on undocumented institutional knowledge, the API is not yet fully GenAI-enabled.

Relationship to This Repository

API contract, semantic context, agent projections, publication and conformance. See also the Agentic Interface overlay.