openapi: 3.1.0
info:
  title: DatasetItem
  version: 1.1.0
  description: >
    Attributes for dataset products exposed via beckn:itemAttributes.
    v1.1 adds streaming transport access methods (MQTT, KAFKA, API, DATA_LAKE)
    and the dataset:streamMeta sub-object for catalog-time stream topology
    metadata. Fully backward-compatible with v1.0.
paths: {}
components:
  schemas:
    DatasetItem:
      type: object
      description: Dataset metadata aligned with schema.org Dataset plus Beckn dataset extensions.
      additionalProperties: true
      required:
        - "schema:identifier"
        - "schema:name"
        - "schema:temporalCoverage"
      properties:
        "@context":
          oneOf:
            - type: string
              format: uri
            - type: array
              items:
                type: string
                format: uri
        "@type":
          type: string
          enum: ["DatasetItem"]
        "schema:identifier":
          type: string
        "schema:name":
          type: string
        "schema:description":
          type: string
        "schema:temporalCoverage":
          type: string
        "schema:spatialCoverage":
          oneOf:
            - type: string
            - type: object
        "schema:license":
          oneOf:
            - type: string
            - type: object
        "schema:distribution":
          type: array
          items:
            type: object
            additionalProperties: true
        "schema:variableMeasured":
          type: array
          items:
            oneOf:
              - type: string
              - type: object
        "schema:measurementTechnique":
          oneOf:
            - type: string
            - type: object
        "schema:usageInfo":
          oneOf:
            - type: string
            - type: object
        "schema:conditionsOfAccess":
          oneOf:
            - type: string
            - type: object
        "schema:temporalResolution":
          oneOf:
            - type: string
            - type: object
        "schema:spatialResolution":
          oneOf:
            - type: string
            - type: object
        "schema:creator":
          oneOf:
            - type: string
            - type: object
        "schema:isBasedOn":
          oneOf:
            - type: string
            - type: array
        "dataset:refreshType":
          type: string
        "dataset:refreshFrequency":
          type: string
        "dataset:granularity":
          type: string
        "dataset:rowCountEstimate":
          type: integer
        "dataset:columnCount":
          type: integer
        "dataset:sensitivityLevel":
          type: string
        "dataset:verticalRange":
          oneOf:
            - type: string
            - type: object
        "dataset:dataType":
          type: string
        "dataset:rawUpdateFrequency":
          type: string
        "dataset:latestRawDataAt":
          type: string
          format: date-time
        "dataset:accessMethod":
          type: string
          description: >
            How the dataset is delivered to the consumer.
            INLINE — data embedded in the beckn message via dataPayload.
            DOWNLOAD — consumer fetches from a URL in schema:distribution.
            DATA_ENCLAVE — consumer accesses data within a secure enclave environment.
            OFF_CHANNEL — delivery arranged outside the beckn network.
            MQTT — real-time push over MQTT 5.0; credentials delivered in DatasetFulfillment after confirm.
            KAFKA — high-throughput event stream via Apache Kafka; credentials delivered in DatasetFulfillment after confirm.
            API — REST API access with API key or bearer token; endpoint and doc URL delivered in DatasetFulfillment after confirm.
            DATA_LAKE — bulk or live delivery to cloud object storage (S3/GCS/ADLS); credentials delivered in DatasetFulfillment after confirm.
          enum:
            - INLINE
            - DOWNLOAD
            - DATA_ENCLAVE
            - OFF_CHANNEL
            - MQTT
            - KAFKA
            - API
            - DATA_LAKE
        "dataset:streamMeta":
          type: object
          description: >
            Catalog-time metadata describing the stream topology. Present when
            dataset:accessMethod is MQTT, KAFKA, API, or DATA_LAKE. Conveys
            what the stream looks like (format, frequency, message schema) without
            exposing credentials. Credentials are provisioned in DatasetFulfillment
            after the buyer confirms the order.
          additionalProperties: true
          properties:
            "dataset:streamProtocol":
              type: string
              description: Transport protocol — informational mirror of accessMethod.
              enum: [MQTT, KAFKA, API, DATA_LAKE]
            "dataset:messageFormat":
              type: string
              description: >
                Encoding format for stream messages or delivered files.
                Examples: JSON, NDJSON, Avro, Protobuf, Parquet, CSV.
            "dataset:updateFrequency":
              type: string
              description: >
                How often new data arrives. ISO 8601 duration (e.g. PT15M)
                or the literal REAL_TIME for sub-second streams.
            "dataset:messageSchemaUrl":
              type: string
              format: uri
              description: >
                URL to the message or file schema (JSON Schema, Avro schema,
                Protobuf descriptor, or OpenAPI spec). Consumers use this to
                configure deserializers before the stream starts.
        "dataset:dataPayload":
          description: >
            Optional inline data payload. When present, carries the actual dataset
            content within the beckn message. The @context URI must resolve to a
            valid schema that describes the payload structure. Used when
            dataset:accessMethod is INLINE.
          type: object
          required:
            - "@context"
            - "@type"
          additionalProperties: true
          properties:
            "@context":
              description: JSON-LD context URI resolving to the payload's schema.
              oneOf:
                - type: string
                  format: uri
                - type: array
                  items:
                    type: string
                    format: uri
            "@type":
              description: The type of data payload (e.g., MeterData, BillingSummary, UtilityCustomerCredential).
              type: string
        "dataset:qualityFlags":
          type: object
          additionalProperties: true
          properties:
            "dataset:gapFilledPercent":
              type: number
            "dataset:outlierRemovedPercent":
              type: number
            "dataset:latencyMinutes":
              type: integer
            "dataset:uptime99DayPercent":
              type: number
            "dataset:validationMethod":
              type: string