teatro-codex-macos-prompt-field-guide.git · openapi.yaml

teatro-codex-macos-prompt-field-guide.git / openapi.yaml

revision 77d9fbdeb6f621ea3fbcc7f49c28263910a87bad · complete file

openapi: 3.1.0
info:
  title: Teatro Prompt Language API
  version: 1.0.0
  description: |
    One-file OpenAPI spec that expresses the Teatro prompt language as data schemas
    and a small set of operations for validation, rehearsal, comparison, and merge.
    This represents the DSL as structured JSON rather than the symbolic notation.

    Source reference: README, parts/ (01–16), quick-reference, examples.
servers: []
paths:
  /validate:
    post:
      summary: Validate a Teatro score document
      operationId: validateScore
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeatroScore'
      responses:
        '200':
          description: Validation result
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        path: { type: string }
                        message: { type: string }
                required: [ok, errors]

  /render:
    post:
      summary: Normalize a Teatro score (e.g., expand symbols to canonical values)
      operationId: renderScore
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                score: { $ref: '#/components/schemas/TeatroScore' }
                options:
                  type: object
                  properties:
                    expandSymbols: { type: boolean, default: true }
                    compactLayers: { type: boolean, default: false }
              required: [score]
      responses:
        '200':
          description: Normalized score
          content:
            application/json:
              schema:
                type: object
                properties:
                  score: { $ref: '#/components/schemas/TeatroScore' }
                  normalized: { type: boolean }
                required: [score, normalized]

  /rehearse:
    post:
      summary: Apply meta-commands (conductor directives) to a score
      operationId: rehearseScore
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                score: { $ref: '#/components/schemas/TeatroScore' }
                directives:
                  type: array
                  items: { $ref: '#/components/schemas/MetaCommand' }
              required: [score, directives]
      responses:
        '200':
          description: Result after applying directives
          content:
            application/json:
              schema:
                type: object
                properties:
                  score: { $ref: '#/components/schemas/TeatroScore' }
                required: [score]

  /merge:
    post:
      summary: Merge two scores
      operationId: mergeScores
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                a: { $ref: '#/components/schemas/TeatroScore' }
                b: { $ref: '#/components/schemas/TeatroScore' }
                strategy:
                  type: string
                  enum: [prefer_a, prefer_b, interleave]
                  default: interleave
              required: [a, b]
      responses:
        '200':
          description: Merged score
          content:
            application/json:
              schema:
                type: object
                properties:
                  score: { $ref: '#/components/schemas/TeatroScore' }
                required: [score]

  /compare:
    post:
      summary: Compare two scores and return structured differences
      operationId: compareScores
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                a: { $ref: '#/components/schemas/TeatroScore' }
                b: { $ref: '#/components/schemas/TeatroScore' }
              required: [a, b]
      responses:
        '200':
          description: Differences between A and B
          content:
            application/json:
              schema:
                type: object
                properties:
                  diffs:
                    type: array
                    items:
                      type: object
                      properties:
                        path: { type: string }
                        before: {}
                        after: {}
                        note: { type: string }
                required: [diffs]

components:
  schemas:
    TeatroScore:
      type: object
      additionalProperties: false
      properties:
        metadata:
          $ref: '#/components/schemas/ScoreHeader'
        acts:
          type: array
          minItems: 1
          items: { $ref: '#/components/schemas/Act' }
      required: [metadata, acts]
      examples:
        - metadata:
            title: Still Reflection
            version: '1.0'
            date: '2025-10-27'
            palette: calm
            tempo: steady
            register: expressive
            anchor: affect
          acts:
            - title: Awakening
              scenes:
                - title: First Light
                  frames:
                    - id: F1
                      commentary: the window breathes open
                      gesture:
                        tempo: steady
                        light: diffuse
                        motion: [drift]
                        energy: steady
                        durationSeconds: 4
                    - id: F2
                      commentary: attention focuses without rush
                      gesture:
                        tempo: steady
                        light: clear
                        motion: [pulse]
                        energy: rise
                        durationSeconds: 2
                  curtain: baseline
            - title: Resolution
              scenes:
                - title: Return
                  frames:
                    - id: F3
                      commentary: fade to internal stillness
                      gesture:
                        tempo: steady
                        light: partial
                        motion: [breathe]
                        energy: fall
                        durationSeconds: 5
                  curtain: memory

    ScoreHeader:
      type: object
      additionalProperties: false
      properties:
        title: { type: string }
        version: { type: string }
        date: { type: string, format: date }
        palette: { type: string, description: 'Aesthetic palette label (e.g., calm, neutral, contrast)' }
        tempo: { $ref: '#/components/schemas/Tempo' }
        register: { $ref: '#/components/schemas/Register' }
        anchor: { type: string, description: 'Context anchor (e.g., app, stage, affect, narrative, perception, session)' }
      required: [title, version, date, register]

    Act:
      type: object
      additionalProperties: false
      properties:
        title: { type: string }
        scenes:
          type: array
          minItems: 1
          items: { $ref: '#/components/schemas/Scene' }
      required: [title, scenes]

    Scene:
      type: object
      additionalProperties: false
      properties:
        title: { type: string }
        camera:
          $ref: '#/components/schemas/CameraCue'
        frames:
          type: array
          minItems: 1
          items: { $ref: '#/components/schemas/Frame' }
        curtain:
          $ref: '#/components/schemas/CurtainType'
      required: [title, frames]

    Frame:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          pattern: '^F[0-9]+$'
        gesture:
          $ref: '#/components/schemas/Gesture'
        mood: { type: string }
        focus: { type: string }
        commentary: { type: string }
        camera:
          $ref: '#/components/schemas/CameraCue'
        layers:
          type: array
          items: { $ref: '#/components/schemas/Layer' }
        meta:
          type: array
          items: { $ref: '#/components/schemas/MetaCommand' }
      required: [id, gesture]

    Layer:
      type: object
      additionalProperties: false
      properties:
        name: { type: string }
        gestures:
          type: array
          minItems: 1
          items: { $ref: '#/components/schemas/Gesture' }
      required: [name, gestures]

    Gesture:
      type: object
      additionalProperties: false
      properties:
        tempo: { $ref: '#/components/schemas/Tempo' }
        light: { $ref: '#/components/schemas/Light' }
        motion:
          type: array
          items: { $ref: '#/components/schemas/MotionVerb' }
        energy: { $ref: '#/components/schemas/EnergyCurve' }
        durationSeconds:
          type: number
          minimum: 0
        operators:
          type: array
          items: { $ref: '#/components/schemas/OperatorInstruction' }
      required: [tempo, light]

    OperatorInstruction:
      type: object
      additionalProperties: false
      properties:
        operator: { $ref: '#/components/schemas/Operator' }
        target:
          type: string
          enum: [light, motion, tempo, camera, energy]
        factor:
          type: number
          description: Scalar like @2x or 0.5 for softening
        notes: { type: string }
      required: [operator]

    CameraCue:
      type: object
      additionalProperties: false
      properties:
        path:
          type: array
          items: { $ref: '#/components/schemas/CameraFraming' }
          minItems: 1
        lensFNumber:
          type: number
          minimum: 1.2
          maximum: 22
        focusMode:
          type: string
          enum: [rack, pull, lock]
        move:
          $ref: '#/components/schemas/CameraMove'

    MetaCommand:
      type: object
      additionalProperties: false
      properties:
        type:
          type: string
          enum: [
            focus_on_stage,
            rehearse_variant,
            freeze_frame,
            restore_frame,
            shift_register,
            compress_timeline,
            expand_timeline,
            wipe_stage
          ]
        params:
          type: object
          additionalProperties: true
          properties:
            frameId: { type: string }
            toRegister: { $ref: '#/components/schemas/Register' }
            factor: { type: number }
      required: [type]

    Tempo:
      type: string
      enum: [steady, moderate, quick, still]
      description: '♩ steady · ♪ moderate · ♬ quick · 𝄐 still'

    Light:
      type: string
      enum: [clear, diffuse, partial, dark]
      description: '☀ clear · ☁ diffuse · 🌒 partial · 🌑 dark'

    MotionVerb:
      type: string
      enum: [drift, pulse, pivot, collapse, unfold, breathe]

    EnergyCurve:
      type: string
      enum: [rise, fall, delay_resolve, oscillate, steady]
      description: '∧ rise · ∨ fall · S delay→resolve · ~ oscillate · — steady'

    Operator:
      type: string
      enum: [amplify, soften, invert, dissolve, echo, sharpen, blur, mirror, merge, split, hybrid]
      description: '↑ amplify · ↓ soften · ¬ invert · ⊹ dissolve · ∿ echo · ⧉ sharpen · ◌ blur · ↔ mirror · ⊕ merge · ⊖ split · ⊛ hybrid'

    CameraFraming:
      type: string
      enum: [WS, MS, CU, POV, OTS]

    CameraMove:
      type: string
      enum: [pan, tilt, zoom, dolly, orbit]

    CutType:
      type: string
      enum: [match, cross_fade, jump, dissolve]

    TransitionType:
      type: string
      enum: [forward, recall, dialogue, loop, crossfade, cut]

    CurtainType:
      type: string
      enum: [baseline, memory, unresolved]

    Register:
      type: string
      enum: [technical, expressive, psychological]