open-reuse/schemas/integration.schema.yaml

$schema: https://json-schema.org/draft/2020-12/schema
$id: https://open-reuse.local/schemas/integration.schema.yaml
title: Integration Definition
description: >
  JSON Schema for open-reuse Integration Definition files (YAML). Aligns with
  INTENT.md, ProductRequirementsDocument.md section 14.1, and registry format v0.1.
type: object
additionalProperties: false
required:
  - schema_version
  - id
  - name
  - upstream
  - reuse
  - boundary
  - validation
  - maintenance
properties:
  schema_version:
    type: string
    enum:
      - open-reuse.integration.v0.1
      - open-reuse.integration.v1
    description: >
      Schema version. v0.1 is the canonical registry format; v1 is accepted for
      early adopters and will converge on v0.1 field names.
  id:
    type: string
    pattern: '^[a-z][a-z0-9-]*$'
    description: Stable integration identifier (kebab-case slug).
  name:
    type: string
    minLength: 1
    description: Human-readable integration name.
  description:
    type: string
    description: Optional summary of the integration purpose and value.
  status:
    $ref: '#/$defs/lifecycleStatus'
  owner:
    type: string
    description: Team, repository, or accountable party for the integration asset.
  local:
    type: object
    additionalProperties: false
    properties:
      repo:
        type: string
        description: Repository hosting the integration implementation.
      path:
        type: string
        description: Path to the integration definition file within the repo.
      system:
        type: string
        description: Local consuming system or product name.
  upstream:
    type: object
    additionalProperties: false
    required:
      - name
    properties:
      name:
        type: string
        minLength: 1
      project_url:
        type: string
        format: uri
      homepage:
        type: string
        format: uri
      version_policy:
        type: string
        description: >
          Accepted upstream version range or tracking policy (e.g. semver range,
          major-line policy, or tag pattern).
      current_version:
        type: string
        description: Pinned or last-validated upstream version reference.
      monitor:
        type: object
        additionalProperties: false
        properties:
          releases:
            type: boolean
          tags:
            type: boolean
          security_advisories:
            type: boolean
          license_changes:
            type: boolean
  reuse:
    type: object
    additionalProperties: false
    required:
      - primary_reuse_mode
    properties:
      primary_reuse_mode:
        $ref: '#/$defs/reuseMode'
      secondary_reuse_modes:
        type: array
        items:
          $ref: '#/$defs/reuseMode'
      risk_level:
        type: string
        enum: [low, low-medium, medium, high, very-high]
      rationale:
        type: string
        description: Why this reuse mode classification applies.
  boundary:
    type: object
    description: >
      Explicit seam between the local system and reused upstream functionality.
      Domain-specific keys are allowed beyond the recommended fields.
    minProperties: 1
    properties:
      type:
        type: string
        enum:
          - interface
          - port
          - adapter
          - wrapper-service
          - api-facade
          - plugin-boundary
          - cli-boundary
          - schema-boundary
          - event-contract
          - file-copy-boundary
      local_adapter:
        type: string
      local_interface:
        type: string
      reused_surface:
        type: string
      entry_point:
        type: string
      contracts:
        type: array
        items:
          type: string
      fragility_points:
        type: array
        items:
          type: string
    additionalProperties: true
  runtime:
    type: object
    additionalProperties: true
    description: Optional runtime assumptions required for the integration.
  permissions:
    type: object
    additionalProperties: true
    description: Optional permission or capability model mapping.
  validation:
    type: object
    additionalProperties: false
    required:
      - harness
    properties:
      harness:
        type: string
        minLength: 1
        description: Command or reference to the validation harness entry point.
      skip_without_runtime:
        type: boolean
      checks:
        type: array
        items:
          type: string
      policy:
        type: string
        enum:
          - required-before-update
          - advisory
          - on-escalation-only
  update_policy:
    type: object
    additionalProperties: false
    properties:
      default_action:
        type: string
        enum:
          - ignore
          - monitor-only
          - open-issue
          - open-update-proposal
          - open-pull-request
          - auto-merge-after-validation
          - require-maintainer-review
          - block-update
          - escalate
      auto_eligible:
        type: boolean
        description: Whether automation may attempt updates without review.
  risks:
    type: object
    additionalProperties: false
    properties:
      sensitivity:
        type: array
        items:
          type: string
      escalation_triggers:
        type: array
        items:
          type: string
  maintenance:
    type: object
    additionalProperties: false
    minProperties: 1
    properties:
      maintainers:
        type: array
        minItems: 1
        items:
          type: string
        description: People, teams, or automation identities accountable for review.
      escalation_conditions:
        type: array
        items:
          type: string
      last_validated:
        type: string
        format: date
      notes:
        type: string
  audit:
    type: object
    additionalProperties: false
    properties:
      registered_at:
        type: string
        format: date
      updated_at:
        type: string
        format: date
      registered_by:
        type: string
$defs:
  lifecycleStatus:
    type: string
    enum:
      - draft
      - registered
      - active
      - needs_review
      - degraded
      - paused
      - deprecated
      - retired
  reuseMode:
    type: string
    enum:
      - dependency
      - dependency-reuse
      - plugin
      - adapter
      - component-extraction
      - patch-overlay
      - fork-continuation
      - cli-boundary