Jira progress: loading…

SSSR-JSON

JSON Registry (JSON Signal Library)

(Addendum to SSSR – Smart Searchable Signal Registry)

1. Purpose of the SSSR-JSON Registry

The existing SSSR is optimized for flat, tabular metadata. However, many ESG signals require structured, nested, rule-rich data models that cannot be represented in spreadsheets without loss of fidelity. Examples include:

XBRL/iXBRL objects
ESRS narrative blocks with metadata
Micro-engine configuration payloads
LCA datasets (process trees, multi-factor emission models)
Complex policy templates with placeholders
Large rule sets (validation matrices, risk maps, NACE→metric mappings)

To handle these safely, ZAYAZ introduces a separate SSSR-JSON Registry: a canonical library of versioned JSON schemas and JSON payloads, fully searchable, traceable, and integrated into the USO/ZAR/SSSR framework.

The registry serves as the authoritative source for all structured ESG logic, ensuring:

Standardization of complex ESG objects
Version control & change governance (CMCB compliance)
Full ESRS/CSRD traceability
Interoperability between engines (FOGE, ZARA, MICE, DICE, VTE, Agents)
High-fidelity validation (JSON schema enforcement)
Auditability & immutability (ALTD + Blockchain Verification Layer)

2. Architectural Overview

2.1. Position in the ZAYAZ Architecture

The SSSR-JSON Registry integrates into the following stack layers:

SSSR → metadata discovery (signal-level)
ZAR → artifact storage (JSON = an artifact class)
USO → semantic linking and ontology tagging
ZSSR → routing to engines that consume/produce JSON
ALTD → logging every JSON registry interaction
CMCB → schema evolution, compatibility rules

JSON artifacts flow to:

FOGE (form templates, structured instructions)
ZARA (intent resolver rulesets)
ZAAM agents (prompt templates, rules)
MICE engines (config, factor tables, scoring logic)
DaVE/DICE/VTE (advanced validation profiles)
XBRL exporter (taxonomy fragments)
Analytics & SIS (scheduler config, event rules)

3. What Belongs in the JSON Registry vs. Normal SSSR?

Category	SSSR Table (Flat)	SSSR-JSON Registry
Simple fields (units, labels, source, IDs)	✔	–
Dropdown lists	✔	–
Single values	✔	–
Complex rulesets	–	✔
XBRL taxonomy fragments	–	✔
Large policy templates	–	✔
MICE engine configs	–	✔
NACE→metric data models	–	✔
LCA / IPCC factor trees	–	✔
Multi-language blocks	–	✔
Agent prompt templates	–	✔
Time-series schema	–	✔
Semantic graphs	–	✔

4. JSON Registry Master Table (Database Specification)

This table registers every JSON artifact that exists in ZAYAZ. Stored in sssr_json_registry.

4.1. Fields

Field	Type	Description
json_id	UUID / string	Unique identifier (e.g., json.nace.tree.v1)
title	string	Human-readable name
description	text	What this JSON object represents
category	enum	(`xbrl`, `form_template`, `policy_block`, `ruleset`, `mice_config`, `validator_profile`, `agent_template`, `ontology_map`, etc.)
version	semver	1.0.0, updated under CMCB rules
status	enum	(active, deprecated, archived, experimental)
json_schema_id	ref	Link to schema defining required structure
data	JSONB	The actual JSON content
checksum_sha256	string	Hash for tamper detection
uso_tags	array	Mapped concepts from the Universal Signal Ontology
related_signals	array(signal_id)	Signals that rely on this artifact
related_engines	array(engine_id)	MICE or AISIM engines using this JSON
related_agents	array(agent_id)	ZAAM agents referencing this
source_reference	array	IPCC, EFRAG, ESRS, ISO references
created_at	timestamp	Registry timestamp
updated_at	timestamp	Auto-updated
change_log	array	History of modifications (CMCB), including diff summaries
security_class	enum	(public, internal, restricted)
blockchain_tx	string	Hash to immutable ledger (optional)

This ensures all JSON artifacts are discoverable, traceable, auditable, and versioned.

5. JSON Schema Table

Stored in sssr_json_schemas. Each schema defines expected structure for categories of JSON artifacts.

Field	Description
schema_id	Unique ID
category	JSON category
version	Schema version
schema	JSON Schema (draft-2020-12)
description	Notes
status	Active/Deprecated

This enforces structural consistency across all engines using the JSON.

6. Examples of JSON Artifacts

6.1. Example: MICE Engine Configuration

mice-engine-configuration.jsonGitHub ↗
{
  "engine_id": "MEID_CALC03_v1",
  "factor_source": "IPCC 2006",
  "unit": "kgCO2e",
  "calculation_rules": {
    "formula": "distance_km * factor_kg_per_km",
    "validity": ["scope3.category6"]
  },
  "defaults": {
    "factor_kg_per_km": 0.143
  }
}

6.2. Example: Form Template Block for FOGE

foge-form-template-block.jsonGitHub ↗
{
  "section": "water_use",
  "fields": [
    {
      "id": "water_withdrawal",
      "type": "numeric",
      "unit": "m3",
      "help": {
        "en": "Enter total water withdrawal.",
        "es": "Ingrese la extracción total de agua."
      }
    }
  ]
}

6.3. Example: Agent Prompt Template

agent-prompt-template.jsonGitHub ↗
{
  "agent_id": "form_diagnostic_assistant",
  "template_id": "scope3_cat4_help_v2",
  "language": "en",
  "prompt": "The user is entering Scope 3 Category 4 data. Validate the input using rules from {json_id:rules.scope3.v2}."
}

7. Governance & Versioning (CMCB Compliance)

MAJOR (breaking)

Schema change
Removal/rename of fields
Migration: required
Deprecation window: 6–12 months

MINOR (non-breaking)

New optional fields
Extended rules
Auto-version: minor bump

PATCH

Typo fixes
Metadata updates
Silent version bump

Governance rules All must be logged in:

schema_audit_log
ZAR artifact history
ALTD for all reads/writes
Blockchain verification layer for critical ESG-impacting JSON

8. Querying the JSON Registry

The registry becomes part of SSSR search, with SSSR+JSON unified search: Query example (SSSR unified search):

search: “scope 3 factors + ruleset + NACE agriculture”
→ returns signals + JSON artifacts + engines + agents

9. Integration With Engines

Engine/Module	Interaction with JSON Registry
FOGE	loads templates, layouts, blocks
ZARA	loads intent → tasks rulesets
ZAAM Agents	pulls prompt templates / logic trees
MICE	fetches engine configs
DICE/DaVE/VTE	loads advanced validator models
XBRL/iXBRL Exporter	loads ESRS taxonomy fragments
SEEL	loads stakeholder logic
ALTD	logs each JSON reference

10. Summary

The SSSR-JSON Registry becomes the central library for all complex, structured, multi-layered ESG intelligence in ZAYAZ. It:

Complements the existing SSSR (flat tables)
Powers dynamic engines (FOGE, ZARA, MICE, DICE)
Enables strict governance (CMCB, ALTD, Blockchain)
Gives white-label partners a stable, versioned API of ESG artifacts
Supports full ESRS/CSRD digital compliance (XBRL aligned)

It is the backbone of structured logic in the ZAYAZ platform.

11. Sequence Diagram — JSON Registry Read Flow (Engine Consumption)

Example: FOGE requesting a JSON form template block

User → Frontend
Frontend → FOGE: Request “Generate CSRD Form”
FOGE → SSSR: Query signals needed
SSSR → SSSR-JSON Registry: Fetch JSON metadata (json_id, version, schema)
SSSR-JSON Registry → ZAR: Retrieve JSON artifact payload
ZAR → USO Resolver: Resolve semantic tags, ontology links
USO Resolver → DICE: Validate structural / semantic integrity (optional)
DICE → FOGE: Return validated JSON structure
FOGE → AISIM: Inject contextual explanations (optional)
AISIM → FOGE: Enriched form template
FOGE → Frontend: Render dynamic form
Frontend → User: Form presented

Key Notes

All JSON pulls route through SSSR, ensuring unified Signal–JSON mapping.
ZAR is the authoritative storage of the JSON artifact.
USO provides semantics and inheritance.
DICE ensures trust and correct structure.

12. Sequence Diagram — JSON Registry Write/Update Flow (Governed Update)

Example: Updating a MICE engine configuration or XBRL taxonomy fragment

Admin → Frontend
Frontend → Registry API (Write Endpoint): Upload JSON payload + metadata
Registry API → JSON Schema Validator: Validate against schema_id
JSON Schema Validator → CMCB: Check compatibility rules (major/minor/patch)
CMCB → USO Resolver: Validate semantic tags + ontology constraints
USO Resolver → ZAR: Store new JSON artifact version
ZAR → SSSR-JSON Registry: Register version + metadata + checksum
SSSR-JSON Registry → ALTD: Log governance event (creation/update)
ALTD → Blockchain Verification Layer: Write tamper-proof hash (optional)
Registry API → Admin: Confirm JSON artifact updated

Key Notes

No JSON enters the system without schema validation.
CMCB enforces breaking change policy.
ALTD + Blockchain provide audit-grade traceability.

13. Sequence Diagram — Search Flow (Unified SSSR Query)

Example: Searching “scope 3 category 4 ruleset”

User → Frontend Search Bar
Frontend → SSSR Search API: Query("scope 3 category 4 ruleset")
SSSR Search API → SSSR Table: Search signal metadata
SSSR Search API → SSSR-JSON Registry: Search JSON metadata (tags, ontology, categories)
SSSR-JSON Registry → USO Resolver: Expand semantic graph (map related domains)
USO Resolver → ZAR: (Optional) Fetch top JSON artifacts for preview
ZAR → SSSR Search API: Return JSON links + signal matches
SSSR Search API → Frontend: Consolidated results
Frontend → User: Display unified search results

Search Modes Activated

Keyword search
Ontology-based semantic search (USO)
Category + version filters
Related signals / engines / agents

14. Sequence Diagram — Engine Trigger → JSON Consumption → Output Generation

Example: MICE engine calculating emissions using a JSON-based ruleset

User → Frontend: Submit Input Module (Business Travel)
Frontend → Input Hub: Validate field-level data
Input Hub → Rule Engine: Determine required MICE engine (MEID_CALC03_v1)
Rule Engine → SSSR: Lookup related JSON configs
SSSR → SSSR-JSON Registry: Fetch metadata for calculation ruleset
SSSR-JSON Registry → ZAR: Retrieve JSON ruleset
ZAR → MICE Engine: Deliver ruleset + config
MICE Engine → DaVE: Validate integrity (logical + numeric)
DaVE → MICE Engine: Approved ruleset
MICE Engine: Perform calculation
MICE Engine → DICE: Validate result (coherence, unit, trust thresholds)
DICE → Output Hub: Validated emissions result
Output Hub → Frontend: Display emission outputs
Frontend → User: Final result shown

Key Notes

This flow ensures no engine ever consumes unvalidated JSON.
MICE, DICE, DaVE form a sequencing trio:rules → compute → validate → output.

15. Sequence Diagram — Agent Prompt Resolution via JSON Registry

Example: ZAAM’s Form Diagnostic Assistant pulling a JSON prompt template

User → Frontend: Click “Help” on a form field
Frontend → ZAAM Dispatcher (ZADIF): Request agent help
ZADIF → Agent Profile DB: Determine required agent
ZADIF → SSSR: Fetch agent-related signal metadata
SSSR → SSSR-JSON Registry: Retrieve prompt template JSON
SSSR-JSON Registry → ZAR: Load JSON prompt object
ZAR → Prompt Template Engine: Apply dynamic resolvers
Prompt Template Engine → AIGS: Tag AI-origin metadata + trust profile
AIGS → Agent Engine: Final prompt constructed
Agent Engine → OpenAI API: Generate output
OpenAI API → Agent Engine: Response
Agent Engine → Frontend: Display contextual help
Frontend → User: Inline guidance shown

Key Notes

Every agent prompt is sourced from versioned JSON templates.
AI-origin tagging and trust scores ensure EU AI Act alignment.

16. Sequence Diagram — XBRL/iXBRL Generation Using JSON Registry

Example: Exporting ESRS-aligned XBRL using JSON-based taxonomy fragments

User → FOGE: “Export CSRD in iXBRL format”
FOGE → SSSR: Fetch required metric → XBRL tag mappings
SSSR → SSSR-JSON Registry: Retrieve XBRL taxonomy blocks (JSON)
SSSR-JSON Registry → ZAR: Load taxonomy JSON artifacts
ZAR → XBRL Builder Engine: Merge mappings + facts
XBRL Builder → DaVE/VTE: Validate taxonomy correctness + fact structure
DaVE/VTE → XBRL Builder: Approve or reject
XBRL Builder → Blockchain Verification Layer: Write disclosure integrity stamp
XBRL Builder → Reports Hub: Produce final document
Reports Hub → Frontend → User: Provide downloadable iXBRL report

17. Canonical SSSR JSON Reference Model (v1.0)

While the SSSR-URL registry defines the human-readable string format ([SSSR_REF: ...]), all machine-native systems in ZAYAZ must operate on a structured JSON representation of SSSR references.

This section defines the canonical JSON format for representing references to:

signals (row-level)
global assets
scoped assets (e.g. client-specific branding)
optional provenance metadata

This model ensures:

zero string parsing in backend systems
consistent API contracts
safe AI mutation
clear separation between lookup and provenance
alignment across all engines (FOGE, ZARA, MICE, DICE, APIs)

17.1. Base JSON Structure

base-json-tructure.jsonGitHub ↗
{
  "target": "sssr:<...>",
  "scope_id": "...",
  "source": {
    "registry": "sssr:<table>.<column>",
    "row_id": "..."
  }
}

All fields except target are optional.

17.2. Signal Reference (Row-Level)

signal-reference.jsonGitHub ↗
{
  "target": "sssr:label_elements.label_element_id",
  "row_id": "LEID-0001"
}

Equivalent string form:

[SSSR_REF: sssr:label_elements.label_element_id @ LEID-0001]

17.3. Global Asset Reference

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

Equivalent string form:

[SSSR_REF: sssr:asset.hazard_pictograms.GHS01.gif]

17.4. Scoped Asset Reference (Client-Bound)

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

Equivalent string form:

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

Important:

scope_id is part of the canonical lookup key
in the current model, this is typically client_id

17.5. 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"
  }
}

Equivalent string form:

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

17.6. Multiple References (Structured Form)

Signals

multiple-references-signals.jsonGitHub ↗
{
  "registry": "sssr:code_registry.code_registry_id",
  "ids": ["CR-00213", "CR-00214"]
}

Scoped Assets

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

17.7. Resolver Interpretation Rules

target → defines what to resolve
scope_id → required for scoped asset classes
row_id → required for signal references
source → provenance only (ignored by resolver logic)

Resolution logic:

If target starts with sssr:asset:

If scope_id present → scoped asset lookup
Else → global asset lookup

If target starts with sssr:<table>.<column>:

Use row_id to resolve row-level signal

17.8. Relationship to SSSR-URL

Layer	Format	Usage
Human / Excel / Docs	`[SSSR_REF: ...]`	Readable, editable
API / Backend / AI	JSON structure	Canonical
Export / Audit	Extended JSON	Enriched with provenance

17.9. Design Principles

Never parse strings in backend systems
Always convert [SSSR_REF: ...] → JSON at ingestion boundary
Store structured JSON in DB (jsonb)
Generate string form only for human-facing layers
Treat scope_id as first-class lookup dimension
Keep provenance separate from resolution

17.10. Future Extensions

The model supports additional scoped dimensions:

region_id
verifier_id
partner_id
scenario_id

This allows SSSR to evolve into a fully multi-dimensional reference system without breaking existing references.

GitHub Repo Request for Change (RFC)

1. Purpose of the SSSR-JSON Registry​

2. Architectural Overview​

2.1. Position in the ZAYAZ Architecture​

3. What Belongs in the JSON Registry vs. Normal SSSR?​

4. JSON Registry Master Table (Database Specification)​

4.1. Fields​

5. JSON Schema Table​

6. Examples of JSON Artifacts​

6.1. Example: MICE Engine Configuration​

6.2. Example: Form Template Block for FOGE​

6.3. Example: Agent Prompt Template​

7. Governance & Versioning (CMCB Compliance)​

8. Querying the JSON Registry​

9. Integration With Engines​

10. Summary​

11. Sequence Diagram — JSON Registry Read Flow (Engine Consumption)​

12. Sequence Diagram — JSON Registry Write/Update Flow (Governed Update)​

13. Sequence Diagram — Search Flow (Unified SSSR Query)​

14. Sequence Diagram — Engine Trigger → JSON Consumption → Output Generation​

15. Sequence Diagram — Agent Prompt Resolution via JSON Registry​

16. Sequence Diagram — XBRL/iXBRL Generation Using JSON Registry​

17. Canonical SSSR JSON Reference Model (v1.0)​

17.1. Base JSON Structure​

17.2. Signal Reference (Row-Level)​

17.3. Global Asset Reference​

17.4. Scoped Asset Reference (Client-Bound)​

17.5. Scoped Asset with Provenance​

17.6. Multiple References (Structured Form)​

17.7. Resolver Interpretation Rules​

17.8. Relationship to SSSR-URL​

17.9. Design Principles​

17.10. Future Extensions​

1. Purpose of the SSSR-JSON Registry

2. Architectural Overview

2.1. Position in the ZAYAZ Architecture

3. What Belongs in the JSON Registry vs. Normal SSSR?

4. JSON Registry Master Table (Database Specification)

4.1. Fields

5. JSON Schema Table

6. Examples of JSON Artifacts

6.1. Example: MICE Engine Configuration

6.2. Example: Form Template Block for FOGE

6.3. Example: Agent Prompt Template

7. Governance & Versioning (CMCB Compliance)

8. Querying the JSON Registry

9. Integration With Engines

10. Summary

11. Sequence Diagram — JSON Registry Read Flow (Engine Consumption)

12. Sequence Diagram — JSON Registry Write/Update Flow (Governed Update)

13. Sequence Diagram — Search Flow (Unified SSSR Query)

14. Sequence Diagram — Engine Trigger → JSON Consumption → Output Generation

15. Sequence Diagram — Agent Prompt Resolution via JSON Registry

16. Sequence Diagram — XBRL/iXBRL Generation Using JSON Registry

17. Canonical SSSR JSON Reference Model (v1.0)

17.1. Base JSON Structure

17.2. Signal Reference (Row-Level)

17.3. Global Asset Reference

17.4. Scoped Asset Reference (Client-Bound)

17.5. Scoped Asset with Provenance

17.6. Multiple References (Structured Form)

17.7. Resolver Interpretation Rules

17.8. Relationship to SSSR-URL

17.9. Design Principles

17.10. Future Extensions