openapi: 3.0.3
info:
  title: EPCIS 2.0 REST Discovery Queries API
  description: The Electronic Product Code Information Services (EPCIS) 2.0 REST API, standardized by GS1, enables capture and query of supply chain visibility events associated with RFID and barcode-tagged objects. EPCIS events record the what (EPC/barcode), when (timestamp), where (read point and business location), why (business step and disposition), and how (sensor data) of tagged objects throughout their journey in the supply chain.
  version: 2.0.0
  contact:
    url: https://www.gs1.org/standards/epcis
  license:
    name: GS1 Standards License
    url: https://www.gs1.org/standards/epcis
servers:
- url: https://{host}/epcis
  variables:
    host:
      default: example.com
      description: EPCIS server host
tags:
- name: Queries
  description: Named query management for subscription-based event filtering
paths:
  /queries:
    post:
      operationId: createNamedQuery
      summary: Create Named Query
      description: Create a named EPCIS query for subscription-based event notification
      tags:
      - Queries
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NamedQuery'
      responses:
        '201':
          description: Named query created
          headers:
            Location:
              schema:
                type: string
        '400':
          description: Invalid query definition
        '401':
          description: Unauthorized
    get:
      operationId: getNamedQueries
      summary: List Named Queries
      description: List all named queries registered for the authenticated user
      tags:
      - Queries
      security:
      - BearerAuth: []
      responses:
        '200':
          description: List of named queries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NamedQuery'
        '401':
          description: Unauthorized
  /queries/{queryName}:
    get:
      operationId: getNamedQuery
      summary: Get Named Query
      description: Retrieve details of a specific named query
      tags:
      - Queries
      security:
      - BearerAuth: []
      parameters:
      - name: queryName
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Named query details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NamedQuery'
        '404':
          description: Query not found
    delete:
      operationId: deleteNamedQuery
      summary: Delete Named Query
      description: Delete a named query and all its subscriptions
      tags:
      - Queries
      security:
      - BearerAuth: []
      parameters:
      - name: queryName
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Query deleted
        '404':
          description: Query not found
  /queries/{queryName}/events:
    get:
      operationId: executeNamedQuery
      summary: Execute Named Query
      description: Execute a named query and return matching EPCIS events
      tags:
      - Queries
      security:
      - BearerAuth: []
      parameters:
      - name: queryName
        in: path
        required: true
        schema:
          type: string
      - name: nextPageToken
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Events matching the named query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EPCISEventList'
        '404':
          description: Query not found
components:
  schemas:
    NamedQuery:
      type: object
      properties:
        name:
          type: string
          description: Unique name for the query
        query:
          type: object
          description: Query parameters
        subscriptionID:
          type: string
        reportIfEmpty:
          type: boolean
        initialRecordTime:
          type: string
          format: date-time
    EPCISEventList:
      type: object
      properties:
        '@context':
          type: array
        type:
          type: string
          default: EPCISDocument
        schemaVersion:
          type: string
        creationDate:
          type: string
          format: date-time
        epcisBody:
          type: object
          properties:
            eventList:
              type: array
              items:
                $ref: '#/components/schemas/EPCISEvent'
    EPCISEvent:
      type: object
      properties:
        '@context':
          oneOf:
          - type: string
          - type: array
        type:
          type: string
          enum:
          - ObjectEvent
          - AggregationEvent
          - TransactionEvent
          - TransformationEvent
          - AssociationEvent
        eventTime:
          type: string
          format: date-time
        eventTimeZoneOffset:
          type: string
          example: +00:00
        epcList:
          type: array
          items:
            type: string
          description: List of EPCs (Electronic Product Codes) involved in the event
        action:
          type: string
          enum:
          - ADD
          - OBSERVE
          - DELETE
        bizStep:
          type: string
          description: Business step URI (e.g., urn:epcglobal:cbv:bizstep:shipping)
        disposition:
          type: string
          description: Disposition URI (e.g., urn:epcglobal:cbv:disp:in_transit)
        readPoint:
          type: object
          properties:
            id:
              type: string
              description: URI identifying the read point (specific location)
        bizLocation:
          type: object
          properties:
            id:
              type: string
              description: URI identifying the business location
        bizTransactionList:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              bizTransaction:
                type: string
        sensorElementList:
          type: array
          items:
            type: object
            description: Sensor data associated with the event
        certificationInfo:
          type: string
          description: Certification information for event data quality
      required:
      - type
      - eventTime
      - action
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer