Skip to main content
Jira progress: loading…

SSSR-REFMOD

Canonical Reference Model (JSON)

1. Purpose​

The SSSR Canonical Reference Model defines the unified JSON structure used to represent all references within ZAYAZ.

This includes:

  • Signal references (row-level)
  • Global asset references
  • Scoped asset references (e.g. client branding)
  • Provenance metadata

This model replaces string parsing as the primary mechanism and ensures:

  • Consistent API contracts
  • Structured database storage (jsonb)
  • AI-safe mutation and transformation
  • Deterministic resolution logic
  • Full interoperability across all engines

2. Relationship to Other SSSR Components​

ComponentRole
SSSR-URL RegistryHuman-readable string format [SSSR_REF: ...]
SSSR-JSON RegistryStorage of JSON artifacts (rules, templates, configs)
SSSR Reference Model (this spec)Canonical JSON structure for all references

3. Canonical JSON Structure​

3.1. Base Model​

base-model.jsonGitHub ↗
{
  "target": "string",
  "scope_id": "string | null",
  "row_id": "string | null",
  "source": {
    "registry": "string",
    "row_id": "string"
  }
}

Field Definitions

FieldDescription
targetCanonical SSSR identifier (sssr:...)
scope_idScope identifier (e.g. client_id)
row_idRow identifier for signal references
source.registryOrigin table/column
source.row_idOrigin row

4. Reference Types​

4.1. Signal Reference​

signal-reference.jsonGitHub ↗
{
  "target": "sssr:label_elements.label_element_id",
  "row_id": "LEID-0001"
}
  • Requires row_id
  • Must not use scope_id

4.2. Global Asset Reference​

global-asset-reference.jsonGitHub ↗
{
  "target": "sssr:asset.hazard_pictograms.GHS01.gif"
}
  • No scope_id
  • No row_id

4.3. Scoped Asset Reference (Client-Bound)​

scoped-asset-reference.jsonGitHub ↗
{
  "target": "sssr:asset.client-profiles.css.css",
  "scope_id": "eco-173-123-456-789"
}
  • scope_id is required
  • scope_id is part of the lookup key

4.4. Scoped Asset with Provenance​

scoped-asset-with-provenance.jsonGitHub ↗
{
  "target": "sssr:asset.client-profiles.css.css",
  "scope_id": "eco-173-123-456-789",
  "source": {
    "registry": "sssr:tenant_branding.css_sssr_ref",
    "row_id": "eco-173-123-456-789"
  }
}

5. Resolution Rules​

5.1. Resolver Logic​

  1. If target starts with sssr:asset:
  • If scope_id present → scoped asset lookup
  • Else → global asset lookup
  1. If target starts with sssr:<table>.<column>:
  • Use row_id for lookup
  1. source is ignored by resolver (used only for audit)

5.2. Lookup Keys​

TypeLookup
Signal(table, column, row_id)
Global asset(asset_class, asset_id)
Scoped asset(asset_class, asset_id, scope_id)

6. Validation Rules​

  • target MUST start with sssr:
  • row_id required for signal references
  • scope_id required for scoped asset classes
  • row_id and scope_id must not conflict semantically
  • source.registry must follow sssr:<table>.<column>

7. Type Definitions​

7.1. TypeScript​

type-definitions.tsGitHub ↗
type SSSRRef =
  | { target: string; row_id: string; scope_id?: never }
  | { target: string; scope_id: string; row_id?: never }
  | {
      target: string;
      scope_id?: string;
      source?: { registry: string; row_id?: string };
    };

7.2. JSON Schema (Draft 2020-12)​

json-schema.jsonGitHub ↗
{
  "type": "object",
  "required": ["target"],
  "properties": {
    "target": {
      "type": "string",
      "pattern": "^sssr:"
    },
    "scope_id": {
      "type": ["string", "null"]
    },
    "row_id": {
      "type": ["string", "null"]
    },
    "source": {
      "type": "object",
      "properties": {
        "registry": { "type": "string" },
        "row_id": { "type": "string" }
      }
    }
  }
}

7.3. Python (Pydantic)​

pydantic.pyGitHub ↗
from pydantic import BaseModel
from typing import Optional

class Source(BaseModel):
    registry: str
    row_id: Optional[str]

class SSSRRef(BaseModel):
    target: str
    scope_id: Optional[str]
    row_id: Optional[str]
    source: Optional[Source]

8. Conversion Rules​

8.1. String → JSON​

[SSSR_REF: sssr:asset.client-profiles.css.css @ eco-173-123-456-789]

→

string-to-json.jsonGitHub ↗
{
  "target": "sssr:asset.client-profiles.css.css",
  "scope_id": "eco-173-123-456-789"
}

8.2. JSON → String​

json-to-string.jsonGitHub ↗
{
  "target": "sssr:asset.client-profiles.css.css",
  "scope_id": "eco-173-123-456-789"
}

→

[SSSR_REF: sssr:asset.client-profiles.css.css @ eco-173-123-456-789]

9. Multi-Reference Patterns​

Signals

multi-reference-patterns.jsonGitHub ↗
{
  "registry": "sssr:code_registry.code_registry_id",
  "ids": ["CR-00213", "CR-00214"]
}

Scoped Assets

scoped-assets.jsonGitHub ↗
{
  "target_registry": "sssr:asset.client-profiles",
  "scope_id": "eco-173-123-456-789",
  "ids": ["css.css", "main-logo.gif"]
}

10. Storage Rules​

LayerFormat
DatabaseJSON (jsonb)
APIJSON
UI / Excel[SSSR_REF: ...]
ExportExtended JSON

11. Design Principles​

  • Never parse strings in backend systems
  • Always convert references to JSON at ingestion boundary
  • Treat scope_id as first-class lookup dimension
  • Separate lookup from provenance
  • Keep model extensible for future scopes

12. Future Extensions​

The model supports additional scope dimensions:

  • region_id
  • verifier_id
  • partner_id
  • scenario_id

13. Summary​

The SSSR Reference Model is the core interoperability layer of ZAYAZ.

It ensures:

  • Unified reference handling across all modules
  • Clean separation of concerns (lookup vs provenance)
  • Strong support for white-label multi-tenancy
  • AI-native data structures
  • Future-proof extensibility

This model is mandatory for all:

  • APIs
  • databases
  • engines
  • agents
  • integrations


GitHub RepoRequest for Change (RFC)