openapi.yaml

openapi: 3.0.3
info:
  title: SourceOS/SociOS Metadata Plane API
  version: 2.0.0
  description: |
    The SourceOS/SociOS Metadata Plane API provides REST endpoints for cataloguing physical
    assets, managing datasets and schemas, evaluating access policies, issuing capability
    tokens, recording workflow runs, capturing provenance, and supporting collaboration.

    All request and response bodies are JSON. All identifiers are stable URNs of the form
    `urn:srcos:<type>:<local-id>`.

    ## Authentication
    All endpoints require a Bearer token in the `Authorization` header.

    ## Error format
    Error responses use a standard `{ "code": "...", "message": "...", "details": [...] }`
    envelope defined in the `Error` component schema.

servers:
  - url: https://api.srcos.local
    description: Local development server

tags:
  - name: Physical Assets
    description: Connectors and physical data store assets
  - name: Metadata
    description: Datasets, schemas, fields, glossary, and field mappings
  - name: Governance
    description: Policies, decisions, and capability tokens
  - name: Execution
    description: Workflows, runs, and provenance records
  - name: Collaboration
    description: Comments and ratings

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT or opaque bearer token issued by the SourceOS identity service.
  schemas:
    Error:
      type: object
      description: Standard error response envelope.
      required: [code, message]
      properties:
        code:
          type: string
          description: Machine-readable error code (e.g. "validation_error", "not_found").
        message:
          type: string
          description: Human-readable error message.
        details:
          type: array
          description: Optional list of field-level error details.
          items:
            type: object
            additionalProperties: true

security:
  - bearerAuth: []

paths:
  /v2/connectors:
    post:
      operationId: upsertConnector
      summary: Upsert a Connector
      description: Creates or updates a named connection configuration for a physical data store. Idempotent on `id`.
      tags: [Physical Assets]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: './schemas/Connector.json' }
      responses:
        '200':
          description: Connector created or updated successfully.
        '400':
          description: Request body is malformed JSON.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '401':
          description: Missing or invalid authentication token.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '403':
          description: Authenticated subject is not permitted to upsert connectors.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '422':
          description: Request body is valid JSON but fails schema validation.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }

  /v2/assets:
    post:
      operationId: upsertPhysicalAsset
      summary: Upsert a PhysicalAsset
      description: Creates or updates a physical resource record that references a Connector. Idempotent on `id`.
      tags: [Physical Assets]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: './schemas/PhysicalAsset.json' }
      responses:
        '200':
          description: PhysicalAsset created or updated successfully.
        '400':
          description: Request body is malformed JSON.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '401':
          description: Missing or invalid authentication token.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '403':
          description: Authenticated subject is not permitted to upsert assets.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '422':
          description: Request body is valid JSON but fails schema validation.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }

  /v2/schemas:
    post:
      operationId: upsertSchemaDefinition
      summary: Upsert a SchemaDefinition
      description: Creates or updates a logical schema composed of EntityFields. Idempotent on `id`.
      tags: [Metadata]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: './schemas/SchemaDefinition.json' }
      responses:
        '200':
          description: SchemaDefinition created or updated successfully.
        '400':
          description: Request body is malformed JSON.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '401':
          description: Missing or invalid authentication token.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '403':
          description: Authenticated subject is not permitted to upsert schemas.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '422':
          description: Request body is valid JSON but fails schema validation.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }

  /v2/agreements:
    post:
      operationId: upsertAgreement
      summary: Upsert an Agreement
      description: Creates or updates a data-sharing agreement between one or more parties. Idempotent on `id`.
      tags: [Governance]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: './schemas/Agreement.json' }
      responses:
        '200':
          description: Agreement created or updated successfully.
        '400':
          description: Request body is malformed JSON.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '401':
          description: Missing or invalid authentication token.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '403':
          description: Authenticated subject is not permitted to upsert agreements.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '422':
          description: Request body is valid JSON but fails schema validation.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }

  /v2/glossary:
    post:
      operationId: upsertGlossaryTerm
      summary: Upsert a GlossaryTerm
      description: Creates or updates a business glossary term with synonyms, tags, and authority links. Idempotent on `id`.
      tags: [Metadata]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: './schemas/GlossaryTerm.json' }
      responses:
        '200':
          description: GlossaryTerm created or updated successfully.
        '400':
          description: Request body is malformed JSON.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '401':
          description: Missing or invalid authentication token.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '403':
          description: Authenticated subject is not permitted to upsert glossary terms.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '422':
          description: Request body is valid JSON but fails schema validation.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }

  /v2/datasets:
    post:
      operationId: upsertDataset
      summary: Upsert a Dataset
      description: Creates or updates a governance-annotated logical view of a PhysicalAsset. Idempotent on `id`.
      tags: [Metadata]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: './schemas/Dataset.json' }
      responses:
        '200':
          description: Dataset created or updated successfully.
        '400':
          description: Request body is malformed JSON.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '401':
          description: Missing or invalid authentication token.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '403':
          description: Authenticated subject is not permitted to upsert datasets.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '422':
          description: Request body is valid JSON but fails schema validation.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }

  /v2/fields:
    post:
      operationId: upsertField
      summary: Upsert a Field
      description: Creates or updates a fully annotated, quality-profiled field bound to a Dataset. Idempotent on `id`.
      tags: [Metadata]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: './schemas/Field.json' }
      responses:
        '200':
          description: Field created or updated successfully.
        '400':
          description: Request body is malformed JSON.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '401':
          description: Missing or invalid authentication token.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '403':
          description: Authenticated subject is not permitted to upsert fields.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '422':
          description: Request body is valid JSON but fails schema validation.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }

  /v2/mappings:
    post:
      operationId: upsertMapping
      summary: Upsert a MappingSpec
      description: Creates or updates a field-to-field semantic mapping with confidence evidence. Idempotent on `id`.
      tags: [Metadata]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: './schemas/MappingSpec.json' }
      responses:
        '200':
          description: MappingSpec created or updated successfully.
        '400':
          description: Request body is malformed JSON.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '401':
          description: Missing or invalid authentication token.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '403':
          description: Authenticated subject is not permitted to upsert mappings.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '422':
          description: Request body is valid JSON but fails schema validation.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }

  /v2/policies:
    post:
      operationId: upsertPolicy
      summary: Upsert a Policy
      description: Creates or updates an access-control policy with subject/object/purpose scope and rules. Idempotent on `id`.
      tags: [Governance]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: './schemas/Policy.json' }
      responses:
        '200':
          description: Policy created or updated successfully.
        '400':
          description: Request body is malformed JSON.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '401':
          description: Missing or invalid authentication token.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '403':
          description: Authenticated subject is not permitted to upsert policies.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '422':
          description: Request body is valid JSON but fails schema validation.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }

  /v2/decisions/evaluate:
    post:
      operationId: evaluatePolicy
      summary: Evaluate a policy decision
      description: |
        Evaluates all applicable Policies for the given subject, object, and purpose triple and
        returns a signed PolicyDecision (permit, deny, or permitWithObligations).

        The decision is persisted for audit purposes and its URN is returned in the response.
        Use the returned `id` to call `POST /v2/tokens/issue` to receive a CapabilityToken.
      tags: [Governance]
      requestBody:
        required: true
        description: The access request context to evaluate.
        content:
          application/json:
            schema:
              type: object
              required: [subject, object, purpose]
              properties:
                subject:
                  $ref: './schemas/SubjectContext.json'
                object:
                  $ref: './schemas/ObjectContext.json'
                purpose:
                  type: string
                  description: The declared purpose of the access request (e.g. "export", "analytics").
                environment:
                  type: object
                  description: Optional ambient environment attributes (device, location, time) for condition evaluation.
      responses:
        '200':
          description: Policy decision evaluated and persisted.
          content:
            application/json:
              schema: { $ref: './schemas/PolicyDecision.json' }
        '400':
          description: Request body is malformed JSON.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '401':
          description: Missing or invalid authentication token.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '403':
          description: Authenticated subject is not permitted to call the policy evaluation endpoint.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '422':
          description: Request body is valid JSON but fails schema validation.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }

  /v2/tokens/issue:
    post:
      operationId: issueToken
      summary: Issue a CapabilityToken
      description: |
        Issues a short-lived, signed CapabilityToken derived from a PolicyDecision with outcome
        `permit` or `permitWithObligations`. The token scopes the holder to the datasets, fields,
        assets, and operations approved by the decision.
      tags: [Governance]
      requestBody:
        required: true
        description: The PolicyDecision from which to derive the token.
        content:
          application/json:
            schema: { $ref: './schemas/PolicyDecision.json' }
      responses:
        '200':
          description: CapabilityToken issued successfully.
          content:
            application/json:
              schema: { $ref: './schemas/CapabilityToken.json' }
        '400':
          description: Request body is malformed JSON.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '401':
          description: Missing or invalid authentication token.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '403':
          description: The PolicyDecision does not permit token issuance (outcome is deny).
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '422':
          description: Request body is valid JSON but fails schema validation.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }

  /v2/workflows:
    post:
      operationId: upsertWorkflow
      summary: Upsert a WorkflowSpec
      description: Creates or updates a directed acyclic graph of WorkflowNodes with triggers and policy bindings. Idempotent on `id`.
      tags: [Execution]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: './schemas/WorkflowSpec.json' }
      responses:
        '200':
          description: WorkflowSpec created or updated successfully.
        '400':
          description: Request body is malformed JSON.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '401':
          description: Missing or invalid authentication token.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '403':
          description: Authenticated subject is not permitted to upsert workflows.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '422':
          description: Request body is valid JSON but fails schema validation.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }

  /v2/runs:
    post:
      operationId: recordRun
      summary: Record a RunRecord
      description: Persists the audit record of a completed workload execution, referencing the CapabilityToken and DataSphere used. Idempotent on `id`.
      tags: [Execution]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: './schemas/RunRecord.json' }
      responses:
        '200':
          description: RunRecord persisted successfully.
        '400':
          description: Request body is malformed JSON.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '401':
          description: Missing or invalid authentication token.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '403':
          description: Authenticated subject is not permitted to record runs.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '422':
          description: Request body is valid JSON but fails schema validation.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }

  /v2/provenance:
    post:
      operationId: recordProvenance
      summary: Record a ProvenanceRecord
      description: Persists a W3C PROV-compatible lineage record linking a RunRecord to its input and output entities. Idempotent on `id`.
      tags: [Execution]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: './schemas/ProvenanceRecord.json' }
      responses:
        '200':
          description: ProvenanceRecord persisted successfully.
        '400':
          description: Request body is malformed JSON.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '401':
          description: Missing or invalid authentication token.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '403':
          description: Authenticated subject is not permitted to record provenance.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '422':
          description: Request body is valid JSON but fails schema validation.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }

  /v2/comments:
    post:
      operationId: createComment
      summary: Create a Comment
      description: Creates a free-text annotation attached to any addressable object identified by a URN. Idempotent on `id`.
      tags: [Collaboration]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: './schemas/Comment.json' }
      responses:
        '200':
          description: Comment created successfully.
        '400':
          description: Request body is malformed JSON.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '401':
          description: Missing or invalid authentication token.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '403':
          description: Authenticated subject is not permitted to create comments.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '422':
          description: Request body is valid JSON but fails schema validation.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }

  /v2/ratings:
    post:
      operationId: createRating
      summary: Create a Rating
      description: Creates a 1–5 star rating attached to any addressable object. Idempotent on `id`.
      tags: [Collaboration]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: './schemas/Rating.json' }
      responses:
        '200':
          description: Rating created successfully.
        '400':
          description: Request body is malformed JSON.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '401':
          description: Missing or invalid authentication token.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '403':
          description: Authenticated subject is not permitted to create ratings.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
        '422':
          description: Request body is valid JSON but fails schema validation.
          content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }