railiance-fabric/schemas/state-hub-export.schema.yaml

$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://railiance.local/fabric/schemas/state-hub-export.schema.yaml"
title: "FabricGraphExport"
oneOf:
  - $ref: "#/$defs/legacyGraphExport"
  - $ref: "#/$defs/financialGraphExport"

$defs:
  legacyGraphExport:
    type: object
    additionalProperties: false
    required:
      - apiVersion
      - kind
      - nodes
      - edges
    properties:
      apiVersion:
        type: string
        const: railiance.fabric/v1alpha1
      kind:
        type: string
        const: FabricGraphExport
      generated_at:
        type: string
        format: date-time
      source:
        type: object
        additionalProperties: false
        properties:
          repo:
            type: string
          commit:
            type: string
          path:
            type: string
      nodes:
        type: array
        items:
          $ref: "#/$defs/legacyNode"
      edges:
        type: array
        items:
          $ref: "#/$defs/legacyEdge"

  financialGraphExport:
    type: object
    additionalProperties: false
    required:
      - apiVersion
      - kind
      - schema_version
      - netkingdom
      - actors
      - fabrics
      - nodes
      - edges
    properties:
      apiVersion:
        type: string
        const: railiance.fabric/v1alpha2
      kind:
        type: string
        const: FabricGraphExport
      schema_version:
        type: string
        const: financial-fabric-v1
      generated_at:
        type: string
        format: date-time
      source:
        type: object
        additionalProperties: true
      compatibility:
        type: object
        additionalProperties: true
      netkingdom:
        $ref: "#/$defs/netkingdom"
      actors:
        type: array
        items:
          $ref: "#/$defs/actor"
      fabrics:
        type: array
        items:
          $ref: "#/$defs/fabricBoundary"
      nodes:
        type: array
        items:
          $ref: "#/$defs/financialNode"
      edges:
        type: array
        items:
          $ref: "#/$defs/financialEdge"
      unresolved:
        type: array
        items:
          $ref: "#/$defs/unresolvedGap"

  legacyNode:
    type: object
    additionalProperties: false
    required:
      - id
      - kind
      - name
      - repo
      - domain
      - lifecycle
    properties:
      id:
        $ref: "./common.schema.yaml#/$defs/graphId"
      kind:
        type: string
      name:
        type: string
      repo:
        type: string
      domain:
        type: string
      lifecycle:
        type: string
      canon_category:
        type: string
      canon_anchor:
        type: string
      mapping_fit:
        $ref: "#/$defs/mappingFit"
      evidence_state:
        $ref: "#/$defs/evidenceState"
      attributes:
        type: object
        additionalProperties: true

  legacyEdge:
    type: object
    additionalProperties: false
    required:
      - from
      - to
      - type
    properties:
      from:
        $ref: "./common.schema.yaml#/$defs/graphId"
      to:
        $ref: "./common.schema.yaml#/$defs/graphId"
      type:
        type: string
      canonical_type:
        type: string
      canon_anchor:
        type: string
      mapping_fit:
        $ref: "#/$defs/mappingFit"
      display_only:
        type: boolean
      evidence_state:
        $ref: "#/$defs/evidenceState"
      attributes:
        type: object
        additionalProperties: true

  netkingdom:
    type: object
    additionalProperties: false
    required:
      - id
      - name
      - king_actor_id
    properties:
      id:
        $ref: "./common.schema.yaml#/$defs/graphId"
      name:
        type: string
        minLength: 1
      king_actor_id:
        $ref: "./common.schema.yaml#/$defs/graphId"

  actor:
    type: object
    additionalProperties: true
    required:
      - id
      - kind
      - role
      - name
    properties:
      id:
        $ref: "./common.schema.yaml#/$defs/graphId"
      kind:
        type: string
        const: FabricActor
      role:
        type: string
        enum:
          - king
          - lord
          - tenant
          - operator
          - steward
      name:
        type: string
        minLength: 1

  fabricBoundary:
    type: object
    additionalProperties: true
    required:
      - id
      - kind
      - name
      - netkingdom_id
      - status
    properties:
      id:
        $ref: "./common.schema.yaml#/$defs/graphId"
      kind:
        type: string
        enum:
          - Fabric
          - Subfabric
      name:
        type: string
        minLength: 1
      netkingdom_id:
        $ref: "./common.schema.yaml#/$defs/graphId"
      parent_fabric_id:
        anyOf:
          - $ref: "./common.schema.yaml#/$defs/graphId"
          - type: "null"
      lord_actor_id:
        $ref: "./common.schema.yaml#/$defs/graphId"
      tenant_actor_id:
        $ref: "./common.schema.yaml#/$defs/graphId"
      status:
        type: string
        minLength: 1
      boundary:
        type: object
        additionalProperties: true
      evidence_refs:
        type: array
        items:
          $ref: "#/$defs/evidenceRef"

  financialNode:
    type: object
    additionalProperties: false
    required:
      - id
      - kind
      - name
      - containment
      - ownership
      - evidence
    properties:
      id:
        $ref: "./common.schema.yaml#/$defs/graphId"
      kind:
        type: string
      name:
        type: string
        minLength: 1
      repo:
        type: string
      domain:
        type: string
      lifecycle:
        type: string
      containment:
        $ref: "#/$defs/containment"
      ownership:
        $ref: "#/$defs/ownership"
      accounting:
        $ref: "#/$defs/accounting"
      deployment_overlay:
        $ref: "#/$defs/deploymentOverlay"
      evidence:
        $ref: "#/$defs/evidence"
      canon_category:
        type: string
      canon_anchor:
        type: string
      mapping_fit:
        $ref: "#/$defs/mappingFit"
      evidence_state:
        $ref: "#/$defs/evidenceState"
      attributes:
        type: object
        additionalProperties: true

  financialEdge:
    type: object
    additionalProperties: false
    required:
      - from
      - to
      - type
      - relationship_category
      - evidence
    properties:
      id:
        type: string
        minLength: 1
      from:
        $ref: "./common.schema.yaml#/$defs/graphId"
      to:
        $ref: "./common.schema.yaml#/$defs/graphId"
      type:
        type: string
        minLength: 1
      relationship_category:
        type: string
        enum:
          - containment
          - ownership
          - technical
          - utility
          - accounting
          - evidence
      canonical_type:
        type: string
      canon_anchor:
        type: string
      mapping_fit:
        $ref: "#/$defs/mappingFit"
      display_only:
        type: boolean
      evidence_state:
        $ref: "#/$defs/evidenceState"
      provider:
        $ref: "#/$defs/utilitySide"
      consumer:
        $ref: "#/$defs/utilitySide"
      boundary:
        $ref: "#/$defs/boundaryCrossing"
      utility:
        $ref: "#/$defs/utility"
      accounting:
        $ref: "#/$defs/accounting"
      deployment_overlay:
        $ref: "#/$defs/deploymentOverlay"
      evidence:
        $ref: "#/$defs/evidence"
      attributes:
        type: object
        additionalProperties: true
    allOf:
      - if:
          properties:
            relationship_category:
              const: utility
        then:
          required:
            - provider
            - consumer
            - boundary
            - utility

  containment:
    type: object
    additionalProperties: false
    required:
      - netkingdom_id
      - fabric_id
    properties:
      netkingdom_id:
        $ref: "./common.schema.yaml#/$defs/graphId"
      fabric_id:
        $ref: "./common.schema.yaml#/$defs/graphId"
      subfabric_id:
        anyOf:
          - $ref: "./common.schema.yaml#/$defs/graphId"
          - type: "null"
      environment:
        anyOf:
          - type: string
            minLength: 1
          - type: "null"
      deployment_scenario_id:
        anyOf:
          - type: string
            minLength: 1
          - type: "null"

  ownership:
    type: object
    additionalProperties: false
    required:
      - owner_actor_id
      - owner_role
      - resolution
    properties:
      owner_actor_id:
        $ref: "./common.schema.yaml#/$defs/graphId"
      owner_role:
        type: string
        enum:
          - king
          - lord
          - tenant
          - operator
          - steward
      resolution:
        type: string
        enum:
          - explicit
          - inherited
          - unresolved
          - ambiguous
      inherited_from:
        anyOf:
          - $ref: "./common.schema.yaml#/$defs/graphId"
          - type: "null"
      supporting_actor_ids:
        type: array
        items:
          $ref: "./common.schema.yaml#/$defs/graphId"

  utilitySide:
    type: object
    additionalProperties: false
    required:
      - owner_actor_id
      - fabric_id
    properties:
      owner_actor_id:
        $ref: "./common.schema.yaml#/$defs/graphId"
      fabric_id:
        $ref: "./common.schema.yaml#/$defs/graphId"
      subfabric_id:
        anyOf:
          - $ref: "./common.schema.yaml#/$defs/graphId"
          - type: "null"

  boundaryCrossing:
    type: object
    additionalProperties: false
    required:
      - crosses_fabric_boundary
      - crosses_subfabric_boundary
    properties:
      crosses_fabric_boundary:
        type: boolean
      crosses_subfabric_boundary:
        type: boolean

  utility:
    type: object
    additionalProperties: true
    required:
      - utility_type
    properties:
      utility_type:
        type: string
        minLength: 1
      contract_id:
        type: string
      payment_schema_id:
        type: string
      metering_basis:
        type: string
      business_model:
        type: string

  accounting:
    type: object
    additionalProperties: true
    properties:
      cost_center_id:
        type: string
      profit_center_id:
        type: string
      provider_profit_center_id:
        type: string
      consumer_cost_center_id:
        type: string
      allocation_model:
        type: string
      payment_schema_id:
        type: string
      metering_basis:
        type: string
      valid_from:
        type: string
      valid_until:
        anyOf:
          - type: string
          - type: "null"

  deploymentOverlay:
    type: object
    additionalProperties: false
    properties:
      deployment_environment:
        type: string
      deployment_scenario:
        type: string
      routing_authority:
        type: string
      access_zone:
        type: string
      policy_authority:
        type: string
      exposure_class:
        type: string
      route_evidence:
        type: object
        additionalProperties:
          anyOf:
            - type: string
            - type: integer
            - type: number
            - type: boolean
            - type: "null"

  evidence:
    type: object
    additionalProperties: false
    required:
      - state
      - review_state
    properties:
      state:
        $ref: "#/$defs/evidenceState"
      review_state:
        type: string
        enum:
          - accepted
          - candidate
          - needs_review
          - rejected
      confidence:
        type: number
        minimum: 0
        maximum: 1
      refs:
        type: array
        items:
          $ref: "#/$defs/evidenceRef"

  evidenceRef:
    type: object
    additionalProperties: true
    properties:
      id:
        type: string
      source_kind:
        type: string
      source_path:
        type: string
      source_url:
        type: string
      source_repo:
        type: string
      source_commit:
        type: string
      scanner:
        type: string
      scanner_version:
        type: string
      content_hash:
        type: string
      observed_at:
        type: string
        format: date-time

  unresolvedGap:
    type: object
    additionalProperties: true
    required:
      - target_id
      - kind
      - message
    properties:
      target_id:
        type: string
        minLength: 1
      kind:
        type: string
        minLength: 1
      severity:
        type: string
      message:
        type: string
        minLength: 1
      evidence_refs:
        type: array
        items:
          $ref: "#/$defs/evidenceRef"

  mappingFit:
    type: string
    enum:
      - direct
      - partial
      - conflict
      - gap
      - unknown

  evidenceState:
    type: string
    enum:
      - observed
      - declared
      - inferred
      - proposed
      - gap