G3N Common Contract

Appearance

Machine-Readable Schemas ​

This page lists the canonical OpenAPI files for each public API. These files are contract-only and intended for client generation, linting, and drift checks.

OpenAPI (per service) ​

  • UAS: https://doc.g3nretailstack.com/uas/openapi.yaml (API Gateway: POST /uas/stat only)
  • USM: https://doc.g3nretailstack.com/usm/openapi.yaml (sessions + service accounts + API keys)
  • OFM: https://doc.g3nretailstack.com/ofm/openapi.yaml (org/facility/membership/teams/sales channels)
  • MRS: https://doc.g3nretailstack.com/mrs/openapi.yaml (records + tags + list + presign/complete)
  • PVM: https://doc.g3nretailstack.com/pvm/openapi.yaml (supplier/taxonomy/product layer)
  • PMC: https://doc.g3nretailstack.com/pmc/openapi.yaml (publish control + revisions + search)
  • ICS: https://doc.g3nretailstack.com/ics/openapi.yaml (inventory control + stock card)
  • PPM: https://doc.g3nretailstack.com/ppm/openapi.yaml (pricing + promotions)
  • SCM: https://doc.g3nretailstack.com/scm/openapi.yaml (sales orders + returns + tenders)
  • PCM: https://doc.g3nretailstack.com/pcm/openapi.yaml (purchase orders + receipts + invoices)
  • CRM: https://doc.g3nretailstack.com/crm/openapi.yaml (customer + loyalty + stored value)
  • Influencer: https://doc.g3nretailstack.com/influencer/openapi.yaml (attribution + earnings + payouts)
  • Accounting: https://doc.g3nretailstack.com/accounting/openapi.yaml (exportable financial events)
  • IPM: https://doc.g3nretailstack.com/ipm/openapi.yaml (integration plane: webhooks/CDC/bulk)
  • RBS: https://doc.g3nretailstack.com/rbs/openapi.yaml (subscriptions and delivery control)
  • UTL: https://doc.g3nretailstack.com/utl/openapi.yaml (offboarding + exports)

JSON Schema (common envelope) ​

Notes ​

  • OpenAPI files describe API Gateway routes only. Direct Lambda actions (operator-only or internal) are documented elsewhere and are not included here.
  • These schemas are the source for contract tests and drift guards; changes should be coordinated with handlers, docs, CLI, and tests.
  • Links above are direct, downloadable URLs for client generation and tooling.
  • Error envelope schema includes error_code, http_status, retryable, and optional conflict_snapshot for 409s.

Schema evolution and deprecation policy (required) ​

  • Additive changes only within a version (new optional fields, new enum values with safe defaults).
  • No breaking changes to existing fields without a new major version or explicit deprecation window.
  • Required fields may be added only in a new version (or behind a gated new endpoint).
  • Event schemas must increment schema_version for breaking changes and continue emitting the prior version during a transition window (duration policy-defined).
  • Deprecation windows must be published and tracked (minimum 180 days for breaking/required-field changes; 90 days for non-breaking endpoint deprecations).

Draft artifacts (stack modules, implementation in progress) ​

  • ICS/SCM/PCM/PPM/CRM-Loyalty/Influencer/Accounting publish OpenAPI as contract drafts; event schemas live in the repo and are published externally once stabilized.
  • External master data remains direct Lambda + CLI only (no API Gateway OpenAPI), but publishes request/response JSON schema and event schemas.
  • Event schemas embed request context and policy/source references for auditability.