semantic-binding-components.yml

openapi: 3.0.4
info:
  title: Semantic Binding API Components
  version: 0.1.0
  description: Entity schemas, enums, value objects, and path parameters for the Semantic Binding API.
paths: {}
components:
  parameters:
    BindingId:
      name: id
      in: path
      required: true
      description: Identifier of the binding record.
      schema:
        type: string
        format: uuid

  schemas:
    # ---- Shared reference value objects ----------------------------------
    SemanticConceptRefKind:
      type: string
      description: Which kind of semantic concept a [SemanticConceptRef] points at.
      enum:
        - CATALOG_ATTRIBUTE
        - PROFILE_ROLE
        - PROFILE

    SemanticConceptRef:
      type: object
      example:
        kind: CATALOG_ATTRIBUTE
        catalogId: "9f2c1b3e-7a44-4c1e-8b0a-2d6f5e9c1a77"
        attributePath: "address.postalCode"
        profileId: null
        roleId: null
      description: |
        A reference from a live binding into a concept in the semantic model, held by id (and
        optional attribute path / profile role). Discriminated by `kind`; which fields are
        populated depends on it:
          - `CATALOG_ATTRIBUTE`: `catalogId` (plus optional `attributePath`).
          - `PROFILE_ROLE`: `profileId` and `roleId`.
          - `PROFILE`: `profileId`.
      required: [kind]
      properties:
        kind:
          $ref: '#/components/schemas/SemanticConceptRefKind'
        catalogId:
          type: string
          format: uuid
          nullable: true
          description: The semantic catalog id, when referencing a catalog or catalog attribute.
        attributePath:
          type: string
          nullable: true
          description: |
            Dot-separated attribute path within the referenced catalog attribute tree
            (e.g. `address.postal_code`), supporting compound/nested concepts.
        profileId:
          type: string
          format: uuid
          nullable: true
          description: The attribute-profile id, when referencing a profile or a profile role.
        roleId:
          type: string
          nullable: true
          description: The profile role id within `profileId`, when referencing a use-case role.

    ProfileRelationRef:
      type: object
      example:
        profileId: "c4d5e6f7-8a9b-4c0d-8e1f-2a3b4c5d6e7f"
        subjectRole: "employee"
        objectRole: "employer"
        relationType: "employed-by"
      description: |
        A reference into the profile relation a [SemanticRelationshipBinding] realizes, held by
        profile id plus the subject/object role ids and the relation type.
      required: [profileId, subjectRole, objectRole, relationType]
      properties:
        profileId:
          type: string
          format: uuid
          description: The attribute-profile id declaring the relation.
        subjectRole:
          type: string
          description: The profile-local subject ProfileRole.id.
        objectRole:
          type: string
          description: The profile-local object ProfileRole.id.
        relationType:
          type: string
          description: The directed relation id, matching the profile relation's relationType.

    # ---- Party-type binding ----------------------------------------------
    SemanticPartyTypeBinding:
      type: object
      example:
        id: "1b2c3d4e-5f60-4a71-8b92-0c1d2e3f4a5b"
        tenantId: "acme"
        partyType: "natural_person"
        partySubtype: "employee"
        semanticConceptRef:
          kind: CATALOG_ATTRIBUTE
          catalogId: "9f2c1b3e-7a44-4c1e-8b0a-2d6f5e9c1a77"
        createdAt: "2026-01-15T09:30:00Z"
        updatedAt: "2026-01-15T09:30:00Z"
      description: |
        Binds a party type (or subtype string) to a catalog or profile concept,
        so records of that type carry a concept defined in a catalog or profile.
      required: [id, tenantId, partyType, semanticConceptRef, createdAt, updatedAt]
      properties:
        id:
          type: string
          format: uuid
        tenantId:
          type: string
        partyType:
          type: string
          description: The party type this binding applies to (e.g. `organization`, `natural_person`).
        partySubtype:
          type: string
          nullable: true
          description: Optional non-blank CTI subtype string refining `partyType` (e.g. `department`).
        semanticConceptRef:
          $ref: '#/components/schemas/SemanticConceptRef'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    # ---- Party attribute value -------------------------------------------
    SemanticPartyAttributeValue:
      type: object
      example:
        id: "2c3d4e5f-6071-4b82-9ca3-1d2e3f4a5b6c"
        tenantId: "acme"
        partyId: "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d"
        conceptRef:
          kind: CATALOG_ATTRIBUTE
          catalogId: "9f2c1b3e-7a44-4c1e-8b0a-2d6f5e9c1a77"
          attributePath: "address.postalCode"
        attributePath: "address.postalCode"
        value: "1011AB"
        createdAt: "2026-01-15T09:30:00Z"
        updatedAt: "2026-01-15T09:30:00Z"
      description: |
        A semantic attribute value attached to a specific party record, keyed by a catalog or profile
        attribute path so the value preserves its semantic meaning. The value may be a scalar, an
        array, or a nested object.
      required: [id, tenantId, partyId, conceptRef, attributePath, value, createdAt, updatedAt]
      properties:
        id:
          type: string
          format: uuid
        tenantId:
          type: string
        partyId:
          type: string
          format: uuid
          description: The party record this value belongs to.
        conceptRef:
          $ref: '#/components/schemas/SemanticConceptRef'
        attributePath:
          type: string
          description: |
            Dot-separated catalog/profile attribute path the value populates (e.g.
            `address.postal_code`); supports nested compound attributes.
        value:
          description: The attribute value as arbitrary JSON (scalar, array, or nested object).
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    # ---- Relationship binding --------------------------------------------
    SemanticRelationshipBinding:
      type: object
      example:
        id: "4e5f6071-8293-4ca4-9db5-2e3f4a5b6c7d"
        tenantId: "acme"
        relationshipInstanceId: null
        subjectPartyId: "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d"
        objectPartyId: "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f"
        relationType: "employed-by"
        profileRelationRef:
          profileId: "c4d5e6f7-8a9b-4c0d-8e1f-2a3b4c5d6e7f"
          subjectRole: "employee"
          objectRole: "employer"
          relationType: "employed-by"
        createdAt: "2026-01-15T09:30:00Z"
        updatedAt: "2026-01-15T09:30:00Z"
      description: |
        Binds a relationship between two party records (a subject and an object, of a governed
        relation type) to a profile relation, so a relationship between actual parties carries its
        use-case semantics. The same subject party may appear in several bindings with different
        governed relation types (multi-role by construction).
      required: [id, tenantId, subjectPartyId, objectPartyId, relationType, createdAt, updatedAt]
      properties:
        id:
          type: string
          format: uuid
        tenantId:
          type: string
        relationshipInstanceId:
          type: string
          format: uuid
          nullable: true
          description: Optional id of the underlying relationship record the binding annotates.
        subjectPartyId:
          type: string
          format: uuid
          description: The live subject party (the relation's subject endpoint).
        objectPartyId:
          type: string
          format: uuid
          description: The live object party (the relation's object endpoint).
        relationType:
          type: string
          description: The governed directed relation id from the relationship-type registry.
        profileRelationRef:
          allOf:
            - $ref: '#/components/schemas/ProfileRelationRef'
          nullable: true
          description: Optional reference to the profile relation this instance realizes.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    # ---- Service capability ----------------------------------------------
    SemanticServiceCapability:
      type: object
      example:
        id: "5f607182-93a4-4db5-8ec6-3f4a5b6c7d8e"
        tenantId: "acme"
        serviceId: "issuer-employee-badge"
        supportedProfileIds:
          - "c4d5e6f7-8a9b-4c0d-8e1f-2a3b4c5d6e7f"
        supportedSetIds: []
        supportedChannelIds: []
        supportedConcepts:
          - kind: PROFILE
            profileId: "c4d5e6f7-8a9b-4c0d-8e1f-2a3b4c5d6e7f"
        createdAt: "2026-01-15T09:30:00Z"
        updatedAt: "2026-01-15T09:30:00Z"
      description: |
        Declares which semantic concepts, profiles, sets and channels a service can operate
        on, so a portal/form/API/issuer/verifier can advertise its semantic surface.
      required:
        - id
        - tenantId
        - serviceId
        - supportedProfileIds
        - supportedSetIds
        - supportedChannelIds
        - supportedConcepts
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
        tenantId:
          type: string
        serviceId:
          type: string
          description: The service the capability belongs to (e.g. an issuer or verifier service identifier).
        supportedProfileIds:
          type: array
          items:
            type: string
            format: uuid
          description: Attribute-profile ids the service can operate on.
        supportedSetIds:
          type: array
          items:
            type: string
            format: uuid
          description: Attribute-set ids the service can operate on.
        supportedChannelIds:
          type: array
          items:
            type: string
            format: uuid
          description: Channel ids the service can operate on.
        supportedConcepts:
          type: array
          items:
            $ref: '#/components/schemas/SemanticConceptRef'
          description: Catalog/profile semantic concepts the service understands.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    # ---- Source binding --------------------------------------------------
    MaterializationPolicy:
      type: string
      description: |
        Whether a bound source's values are stored or only referenced for governance overlay.
          - `REFERENCE_ONLY`: the source's values are NOT stored; the binding only projects the
            catalog's governance overlays onto the externally-hosted data (a data-map / RoPA over a
            system that is never copied).
          - `STORE`: resolved values are persisted into the party-attribute-value store keyed by the
            bound catalog attribute (an explicit opt-in, since it stores potentially personal data).
      enum:
        - REFERENCE_ONLY
        - STORE

    CatalogRef:
      type: object
      example:
        catalogId: "9f2c1b3e-7a44-4c1e-8b0a-2d6f5e9c1a77"
        catalogVersion: 3
      description: A version-pinned reference to a specific published snapshot of a semantic catalog.
      required: [catalogId, catalogVersion]
      properties:
        catalogId:
          type: string
          format: uuid
        catalogVersion:
          type: integer
          format: int64
          minimum: 1

    AttributeTransformKind:
      type: string
      description: The kind of value transform a [AttributeTransform] describes.
      enum:
        - NONE
        - RENAME_ONLY
        - FORMAT
        - CODE_MAP

    AttributeTransform:
      type: object
      example:
        kind: RENAME_ONLY
        expression: null
        codeMap: {}
        unitConversion: null
      description: An optional value transform applied along a source field mapping (reuses the schema-relationship transform type).
      properties:
        kind:
          allOf:
            - $ref: '#/components/schemas/AttributeTransformKind'
          default: NONE
        expression:
          type: string
          nullable: true
          description: Optional transform expression, for computed transforms.
        codeMap:
          type: object
          description: Optional code/value mapping, for code-list translation.
          additionalProperties:
            type: string
        unitConversion:
          type: string
          nullable: true

    SourceFieldMapping:
      type: object
      example:
        sourceField: "emp_given_name"
        attributePath: "givenName"
        transform: null
      description: |
        Maps ONE source-native field onto ONE catalog attribute. The `sourceField` is the source's own
        opaque key (a DB column, JSON key, IAM claim); the `attributePath` is the clean segment path of
        the catalog attribute it feeds, so the source's data inherits that attribute's governance
        overlays without necessarily storing the value.
      required: [sourceField, attributePath]
      properties:
        sourceField:
          type: string
          description: The source-native field key; non-blank. Never a semantic path.
        attributePath:
          type: string
          description: The catalog attribute path (dot-separated clean segments) this field feeds (e.g. `address.postalCode`).
        transform:
          allOf:
            - $ref: '#/components/schemas/AttributeTransform'
          nullable: true

    SourceEntityBinding:
      type: object
      example:
        entity: "Employee"
        fieldMappings:
          - sourceField: "emp_given_name"
            attributePath: "givenName"
            transform: null
      description: One catalog entity's worth of field bindings, mapping a source's native fields onto the attributes of one catalog entity.
      required: [entity]
      properties:
        entity:
          type: string
          description: The catalog entity name whose attributes the `fieldMappings` target; non-blank.
        fieldMappings:
          type: array
          default: []
          items:
            $ref: '#/components/schemas/SourceFieldMapping'

    SemanticSourceBinding:
      type: object
      example:
        id: "60718293-a4b5-4ec6-9fd7-4a5b6c7d8e9f"
        tenantId: "acme"
        name: "HR system - employee attributes"
        sourcePartyId: "6d9c2a1b-3e44-4f12-9a0b-1c2d3e4f5a6b"
        capabilityId: "b1e2c3d4-5f60-4a71-8b92-0c1d2e3f4a5b"
        catalogRef:
          catalogId: "9f2c1b3e-7a44-4c1e-8b0a-2d6f5e9c1a77"
          catalogVersion: 3
        entityBindings:
          - entity: "Employee"
            fieldMappings:
              - sourceField: "emp_given_name"
                attributePath: "givenName"
                transform: null
        materialization: REFERENCE_ONLY
        createdAt: "2026-01-15T09:30:00Z"
        updatedAt: "2026-01-15T09:30:00Z"
      description: |
        Binds a registered attribute source (a software/server party carrying an `ATTRIBUTE_SOURCE`
        capability) to attributes of a version-pinned catalog, so the source's native fields map onto
        catalog attributes and inherit their governance overlays (classification / processing /
        residency / assurance plus the catalog jurisdictions). Complementary to the static
        `CatalogSchemaBinding` (declarative schema equivalence): this binds a LIVE source. Governance is
        never restated here; it is inherited from the bound catalog attribute, so a derived data-map can
        enumerate the catalog's governance posture per source + field even for a `REFERENCE_ONLY` source
        is never stored.
      required: [id, tenantId, name, sourcePartyId, capabilityId, catalogRef, materialization, createdAt, updatedAt]
      properties:
        id:
          type: string
          format: uuid
        tenantId:
          type: string
        name:
          type: string
          description: Human-readable binding name; non-blank.
        sourcePartyId:
          type: string
          format: uuid
          description: The software/server party that carries the `ATTRIBUTE_SOURCE` capability.
        capabilityId:
          type: string
          format: uuid
          description: The `ATTRIBUTE_SOURCE` capability id on that party.
        catalogRef:
          $ref: '#/components/schemas/CatalogRef'
        entityBindings:
          type: array
          default: []
          items:
            $ref: '#/components/schemas/SourceEntityBinding'
        materialization:
          $ref: '#/components/schemas/MaterializationPolicy'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time