diff --git a/specification/schema/DatasetFulfillment/README.md b/specification/schema/DatasetFulfillment/README.md new file mode 100644 index 0000000..1601e6b --- /dev/null +++ b/specification/schema/DatasetFulfillment/README.md @@ -0,0 +1,31 @@ +# DatasetFulfillment + +Access provisioning details for a fulfilled dataset order — extending [`schema:DataDownload`](https://schema.org/DataDownload) with Beckn-specific attributes for access method, signed URLs, download windows, and (in v1.1+) stream credential delivery. + +Carried as `performanceAttributes` or `fulfillmentAttributes` in beckn messages — typically on the BPP side in `on_confirm` / `on_status` once the buyer has confirmed and credentials are ready. + +## Versions + +| Version | Status | Highlights | +|---|---|---| +| [v1.0](./v1.0) | Stable | Base schema: `accessMethod` (5 values), signed `accessUrl`, access window (`accessStart`/`accessEnd`), download counters, support contact. | +| [v1.1](./v1.1) | Stable | Adds `streamConnection` — polymorphic credential delivery object for `MQTT`, `KAFKA`, `API`, and `DATA_LAKE` access methods. Relaxes required fields so only `accessMethod` is mandatory. Adds `credentialExpiresAt` for short-lived credential rotation via `update`. Fully backward-compatible with v1.0. | + +## File layout + +Each version folder contains: + +- `attributes.yaml` — OpenAPI 3.1 component schema, the canonical structural definition +- `schema.json` — self-contained JSON Schema (draft 2020-12) for runtime validation +- `context.jsonld` — JSON-LD term mappings (each version inherits from the version below) +- `vocab.jsonld` — RDF property declarations +- `README.md` — version notes and examples + +Cross-version concerns (namespace prefixes, class IRI mappings, `rdfs:Class` declarations) live in the parent [`schema/context.jsonld`](../context.jsonld) and [`schema/vocab.jsonld`](../vocab.jsonld) and are inherited by each version. + +## Canonical URLs (after publish) + +``` +https://schema.beckn.io/DatasetFulfillment/v1.0/{attributes.yaml,schema.json,context.jsonld,vocab.jsonld} +https://schema.beckn.io/DatasetFulfillment/v1.1/{attributes.yaml,schema.json,context.jsonld,vocab.jsonld} +``` diff --git a/specification/schema/DatasetFulfillment/v1.0/README.md b/specification/schema/DatasetFulfillment/v1.0/README.md new file mode 100644 index 0000000..a16fec1 --- /dev/null +++ b/specification/schema/DatasetFulfillment/v1.0/README.md @@ -0,0 +1,46 @@ +# DatasetFulfillment — v1.0 + +Base schema for delivering a dataset to a buyer who has confirmed an order. Extends [`schema:DataDownload`](https://schema.org/DataDownload) with Beckn-specific access-window and download-counter attributes. + +Carried by the BPP as `performanceAttributes` (or `fulfillmentAttributes`) in `on_confirm` / `on_status` once the buyer has paid and the BPP is ready to deliver. + +## Required fields + +| Field | Notes | +|---|---| +| `fulfillment:accessMethod` | One of `DOWNLOAD`, `API`, `STREAM`, `DATA_ROOM`, `SFTP`. | +| `fulfillment:accessUrl` | Signed or time-limited URL for retrieval. | +| `fulfillment:accessStart` | ISO 8601 date-time when access opens. | +| `fulfillment:accessEnd` | ISO 8601 date-time when access closes. | + +## Fulfillment example — `DOWNLOAD` + +```json +{ + "@context": "https://schema.beckn.io/DatasetFulfillment/v1.0/context.jsonld", + "@type": "DatasetFulfillment", + "fulfillment:accessMethod": "DOWNLOAD", + "fulfillment:accessUrl": "https://bucket.s3.ap-south-1.amazonaws.com/rainprob-mh-march-2026.parquet?X-Amz-Signature=...", + "fulfillment:accessStart": "2026-04-01T09:00:00Z", + "fulfillment:accessEnd": "2026-04-08T09:00:00Z", + "fulfillment:format": "Parquet", + "fulfillment:fileSizeBytes": 47185920, + "fulfillment:maxDownloads": 3, + "fulfillment:downloadsUsed": 0, + "fulfillment:supportEmail": "support@example.com", + "fulfillment:termsUrl": "https://example.com/dataset-terms", + "fulfillment:attributionText": "© 2026 Example Provider. Licensed under CC-BY-4.0." +} +``` + +## Notes + +- `accessUrl` MUST be short-lived. The BPP signs the URL with a window expressed by `accessStart`/`accessEnd`; outside that window the URL returns 403/404. +- `maxDownloads` is an advisory hint; enforcement is at the signing layer. +- Beckn messages are signed but not encrypted — treat `accessUrl` like a bearer token. Don't put credentials in the URL beyond what's needed for the pre-signed mechanism. + +## Canonical URL + +``` +https://schema.beckn.io/DatasetFulfillment/v1.0/context.jsonld +``` diff --git a/specification/schema/DatasetFulfillment/v1/attributes.yaml b/specification/schema/DatasetFulfillment/v1.0/attributes.yaml similarity index 100% rename from specification/schema/DatasetFulfillment/v1/attributes.yaml rename to specification/schema/DatasetFulfillment/v1.0/attributes.yaml diff --git a/specification/schema/DatasetFulfillment/v1.0/context.jsonld b/specification/schema/DatasetFulfillment/v1.0/context.jsonld new file mode 100644 index 0000000..c95b320 --- /dev/null +++ b/specification/schema/DatasetFulfillment/v1.0/context.jsonld @@ -0,0 +1,19 @@ +{ + "@context": [ + "https://schema.beckn.io/schema/context.jsonld", + { + "@version": 1.1, + "fulfillment:accessMethod": "fulfillment:accessMethod", + "fulfillment:accessUrl": "fulfillment:accessUrl", + "fulfillment:accessStart": "fulfillment:accessStart", + "fulfillment:accessEnd": "fulfillment:accessEnd", + "fulfillment:format": "fulfillment:format", + "fulfillment:fileSizeBytes": "fulfillment:fileSizeBytes", + "fulfillment:maxDownloads": "fulfillment:maxDownloads", + "fulfillment:downloadsUsed": "fulfillment:downloadsUsed", + "fulfillment:supportEmail": "fulfillment:supportEmail", + "fulfillment:termsUrl": "fulfillment:termsUrl", + "fulfillment:attributionText": "fulfillment:attributionText" + } + ] +} diff --git a/specification/schema/DatasetFulfillment/v1.0/schema.json b/specification/schema/DatasetFulfillment/v1.0/schema.json new file mode 100644 index 0000000..c5c4c86 --- /dev/null +++ b/specification/schema/DatasetFulfillment/v1.0/schema.json @@ -0,0 +1,33 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schema.beckn.io/DatasetFulfillment/v1.0/schema.json", + "title": "DatasetFulfillment", + "description": "Access provisioning details for a fulfilled dataset order. Delivery method plus credentials or signed URLs required to retrieve the data. Carried as performanceAttributes / fulfillmentAttributes in beckn messages.", + "type": "object", + "additionalProperties": true, + "required": [ + "fulfillment:accessMethod", + "fulfillment:accessUrl", + "fulfillment:accessStart", + "fulfillment:accessEnd" + ], + "properties": { + "@context": { "type": "string", "format": "uri" }, + "@type": { "type": "string" }, + "fulfillment:accessMethod": { + "type": "string", + "description": "Access method code (DOWNLOAD, API, STREAM, DATA_ROOM, SFTP).", + "enum": ["DOWNLOAD", "API", "STREAM", "DATA_ROOM", "SFTP"] + }, + "fulfillment:accessUrl": { "type": "string", "format": "uri" }, + "fulfillment:accessStart": { "type": "string", "format": "date-time" }, + "fulfillment:accessEnd": { "type": "string", "format": "date-time" }, + "fulfillment:format": { "type": "string" }, + "fulfillment:fileSizeBytes": { "type": "integer" }, + "fulfillment:maxDownloads": { "type": "integer" }, + "fulfillment:downloadsUsed": { "type": "integer" }, + "fulfillment:supportEmail": { "type": "string", "format": "email" }, + "fulfillment:termsUrl": { "type": "string", "format": "uri" }, + "fulfillment:attributionText": { "type": "string" } + } +} diff --git a/specification/schema/DatasetFulfillment/v1/vocab.jsonld b/specification/schema/DatasetFulfillment/v1.0/vocab.jsonld similarity index 84% rename from specification/schema/DatasetFulfillment/v1/vocab.jsonld rename to specification/schema/DatasetFulfillment/v1.0/vocab.jsonld index 6fc0604..c3941ce 100644 --- a/specification/schema/DatasetFulfillment/v1/vocab.jsonld +++ b/specification/schema/DatasetFulfillment/v1.0/vocab.jsonld @@ -1,22 +1,11 @@ { "@context": { "@version": 1.1, - "schema": "https://schema.org/", "fulfillment": "https://beckn.org/schema/dataset-fulfillment#", "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#", - "rdfs": "http://www.w3.org/2000/01/rdf-schema#", - "xsd": "http://www.w3.org/2001/XMLSchema#" + "rdfs": "http://www.w3.org/2000/01/rdf-schema#" }, "@graph": [ - { - "@id": "fulfillment:DatasetFulfillment", - "@type": "rdfs:Class", - "rdfs:label": "DatasetFulfillment", - "rdfs:comment": "Access provisioning details for a fulfilled dataset order.", - "rdfs:subClassOf": { - "@id": "schema:DataDownload" - } - }, { "@id": "fulfillment:accessMethod", "@type": "rdf:Property", @@ -85,4 +74,3 @@ } ] } - diff --git a/specification/schema/DatasetFulfillment/v1.1/README.md b/specification/schema/DatasetFulfillment/v1.1/README.md index e4c58c9..2e34ed9 100644 --- a/specification/schema/DatasetFulfillment/v1.1/README.md +++ b/specification/schema/DatasetFulfillment/v1.1/README.md @@ -1,6 +1,6 @@ # DatasetFulfillment — v1.1 -Extends [v1](../v1/attributes.yaml) with `fulfillment:streamConnection` — a credential delivery object for streaming transport access methods (MQTT, Kafka, REST API, cloud data lake). Fully backward-compatible — all v1 fields remain. +Extends [v1.0](../v1.0/attributes.yaml) with `fulfillment:streamConnection` — a credential delivery object for streaming transport access methods (MQTT, Kafka, REST API, cloud data lake). Fully backward-compatible — all v1.0 fields remain. ## What's new in v1.1 diff --git a/specification/schema/DatasetFulfillment/v1.1/context.jsonld b/specification/schema/DatasetFulfillment/v1.1/context.jsonld index 835c500..9fe691a 100644 --- a/specification/schema/DatasetFulfillment/v1.1/context.jsonld +++ b/specification/schema/DatasetFulfillment/v1.1/context.jsonld @@ -1,64 +1,50 @@ { - "@context": { - "@version": 1.1, - "schema": "https://schema.org/", - "fulfillment": "./vocab.jsonld#", + "@context": [ + "https://schema.beckn.io/DatasetFulfillment/v1.0/context.jsonld", + { + "@version": 1.1, + "fulfillment:streamConnection": "fulfillment:streamConnection", + "fulfillment:credentialExpiresAt": "fulfillment:credentialExpiresAt", - "DatasetFulfillment": "fulfillment:DatasetFulfillment", + "fulfillment:brokerUri": "fulfillment:brokerUri", + "fulfillment:topic": "fulfillment:topic", + "fulfillment:qos": "fulfillment:qos", + "fulfillment:clientId": "fulfillment:clientId", + "fulfillment:username": "fulfillment:username", + "fulfillment:password": "fulfillment:password", + "fulfillment:tlsCaCert": "fulfillment:tlsCaCert", + "fulfillment:sessionExpiry": "fulfillment:sessionExpiry", - "fulfillment:accessMethod": "fulfillment:accessMethod", - "fulfillment:accessUrl": "fulfillment:accessUrl", - "fulfillment:accessStart": "fulfillment:accessStart", - "fulfillment:accessEnd": "fulfillment:accessEnd", - "fulfillment:format": "fulfillment:format", - "fulfillment:fileSizeBytes": "fulfillment:fileSizeBytes", - "fulfillment:maxDownloads": "fulfillment:maxDownloads", - "fulfillment:downloadsUsed": "fulfillment:downloadsUsed", - "fulfillment:supportEmail": "fulfillment:supportEmail", - "fulfillment:termsUrl": "fulfillment:termsUrl", - "fulfillment:attributionText": "fulfillment:attributionText", + "fulfillment:bootstrapServers": "fulfillment:bootstrapServers", + "fulfillment:topicName": "fulfillment:topicName", + "fulfillment:consumerGroupId": "fulfillment:consumerGroupId", + "fulfillment:saslMechanism": "fulfillment:saslMechanism", + "fulfillment:saslUsername": "fulfillment:saslUsername", + "fulfillment:saslPassword": "fulfillment:saslPassword", + "fulfillment:schemaRegistryUrl": "fulfillment:schemaRegistryUrl", + "fulfillment:schemaRegistryUsername": "fulfillment:schemaRegistryUsername", + "fulfillment:schemaRegistryPassword": "fulfillment:schemaRegistryPassword", + "fulfillment:startOffset": "fulfillment:startOffset", - "fulfillment:streamConnection": "fulfillment:streamConnection", - "fulfillment:credentialExpiresAt": "fulfillment:credentialExpiresAt", + "fulfillment:apiEndpoint": "fulfillment:apiEndpoint", + "fulfillment:apiDocUrl": "fulfillment:apiDocUrl", + "fulfillment:authScheme": "fulfillment:authScheme", + "fulfillment:bearerToken": "fulfillment:bearerToken", + "fulfillment:apiKey": "fulfillment:apiKey", + "fulfillment:rateLimitRpm": "fulfillment:rateLimitRpm", - "fulfillment:brokerUri": "fulfillment:brokerUri", - "fulfillment:topic": "fulfillment:topic", - "fulfillment:qos": "fulfillment:qos", - "fulfillment:clientId": "fulfillment:clientId", - "fulfillment:username": "fulfillment:username", - "fulfillment:password": "fulfillment:password", - "fulfillment:tlsCaCert": "fulfillment:tlsCaCert", - "fulfillment:sessionExpiry": "fulfillment:sessionExpiry", - - "fulfillment:bootstrapServers": "fulfillment:bootstrapServers", - "fulfillment:topicName": "fulfillment:topicName", - "fulfillment:consumerGroupId": "fulfillment:consumerGroupId", - "fulfillment:saslMechanism": "fulfillment:saslMechanism", - "fulfillment:saslUsername": "fulfillment:saslUsername", - "fulfillment:saslPassword": "fulfillment:saslPassword", - "fulfillment:schemaRegistryUrl": "fulfillment:schemaRegistryUrl", - "fulfillment:schemaRegistryUsername": "fulfillment:schemaRegistryUsername", - "fulfillment:schemaRegistryPassword": "fulfillment:schemaRegistryPassword", - "fulfillment:startOffset": "fulfillment:startOffset", - - "fulfillment:apiEndpoint": "fulfillment:apiEndpoint", - "fulfillment:apiDocUrl": "fulfillment:apiDocUrl", - "fulfillment:authScheme": "fulfillment:authScheme", - "fulfillment:bearerToken": "fulfillment:bearerToken", - "fulfillment:apiKey": "fulfillment:apiKey", - "fulfillment:rateLimitRpm": "fulfillment:rateLimitRpm", - - "fulfillment:cloudProvider": "fulfillment:cloudProvider", - "fulfillment:accessType": "fulfillment:accessType", - "fulfillment:bucket": "fulfillment:bucket", - "fulfillment:storagePrefix": "fulfillment:storagePrefix", - "fulfillment:presignedUrl": "fulfillment:presignedUrl", - "fulfillment:accessKeyId": "fulfillment:accessKeyId", - "fulfillment:secretAccessKey": "fulfillment:secretAccessKey", - "fulfillment:sessionToken": "fulfillment:sessionToken", - "fulfillment:sasToken": "fulfillment:sasToken", - "fulfillment:storageRegion": "fulfillment:storageRegion", - "fulfillment:fileFormat": "fulfillment:fileFormat", - "fulfillment:partitionPattern": "fulfillment:partitionPattern" - } + "fulfillment:cloudProvider": "fulfillment:cloudProvider", + "fulfillment:accessType": "fulfillment:accessType", + "fulfillment:bucket": "fulfillment:bucket", + "fulfillment:storagePrefix": "fulfillment:storagePrefix", + "fulfillment:presignedUrl": "fulfillment:presignedUrl", + "fulfillment:accessKeyId": "fulfillment:accessKeyId", + "fulfillment:secretAccessKey": "fulfillment:secretAccessKey", + "fulfillment:sessionToken": "fulfillment:sessionToken", + "fulfillment:sasToken": "fulfillment:sasToken", + "fulfillment:storageRegion": "fulfillment:storageRegion", + "fulfillment:fileFormat": "fulfillment:fileFormat", + "fulfillment:partitionPattern": "fulfillment:partitionPattern" + } + ] } diff --git a/specification/schema/DatasetFulfillment/v1.1/schema.json b/specification/schema/DatasetFulfillment/v1.1/schema.json new file mode 100644 index 0000000..baaa172 --- /dev/null +++ b/specification/schema/DatasetFulfillment/v1.1/schema.json @@ -0,0 +1,159 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schema.beckn.io/DatasetFulfillment/v1.1/schema.json", + "title": "DatasetFulfillment", + "description": "Access provisioning details for a fulfilled dataset order. v1.1 adds fulfillment:streamConnection for streaming transport credentials (MQTT, Kafka, REST API, cloud data lake) and relaxes required fields so only accessMethod is mandatory. accessUrl/accessStart/accessEnd are still present and used by DOWNLOAD; streaming methods use streamConnection.credentialExpiresAt instead. Fully backward-compatible with v1.0.", + "type": "object", + "additionalProperties": true, + "required": ["fulfillment:accessMethod"], + "properties": { + "@context": { "type": "string", "format": "uri" }, + "@type": { "type": "string" }, + "fulfillment:accessMethod": { + "type": "string", + "description": "Access method code indicating how the buyer receives the data. DOWNLOAD — time-limited URL fetch (accessUrl required). API — REST API; credentials in streamConnection. STREAM — generic real-time stream. MQTT/KAFKA/DATA_LAKE — credentials in streamConnection. DATA_ROOM — secure data room. SFTP — SFTP server.", + "enum": [ + "DOWNLOAD", + "API", + "STREAM", + "MQTT", + "KAFKA", + "DATA_LAKE", + "DATA_ROOM", + "SFTP" + ] + }, + "fulfillment:accessUrl": { + "type": "string", + "format": "uri", + "description": "Signed or time-limited URL for accessing the dataset. Required when fulfillment:accessMethod is DOWNLOAD." + }, + "fulfillment:accessStart": { + "type": "string", + "format": "date-time", + "description": "Start of the access window (ISO 8601 date-time)." + }, + "fulfillment:accessEnd": { + "type": "string", + "format": "date-time", + "description": "End of the access window. For streaming methods, use streamConnection.credentialExpiresAt instead." + }, + "fulfillment:format": { + "type": "string", + "description": "File or message format (Parquet, CSV, JSON, Avro, NDJSON, ...)." + }, + "fulfillment:fileSizeBytes": { + "type": "integer", + "description": "Approximate size of the delivered file in bytes (DOWNLOAD only)." + }, + "fulfillment:maxDownloads": { + "type": "integer", + "description": "Maximum number of times the dataset can be downloaded (DOWNLOAD only)." + }, + "fulfillment:downloadsUsed": { + "type": "integer", + "description": "Number of downloads already used by the buyer (DOWNLOAD only)." + }, + "fulfillment:supportEmail": { "type": "string", "format": "email" }, + "fulfillment:termsUrl": { "type": "string", "format": "uri" }, + "fulfillment:attributionText": { "type": "string" }, + "fulfillment:streamConnection": { + "type": "object", + "description": "Stream connection credentials provisioned for the buyer after confirm. Required when accessMethod is MQTT, KAFKA, API, or DATA_LAKE. All credentials MUST be short-lived; set credentialExpiresAt and instruct the buyer to call update before expiry for rotation. The @type discriminator determines which credential fields apply.", + "additionalProperties": true, + "properties": { + "@type": { + "type": "string", + "description": "Credential shape discriminator.", + "enum": [ + "MQTTConnection", + "KafkaConsumerCredentials", + "ApiCredential", + "DataLakeCredential" + ] + }, + "fulfillment:credentialExpiresAt": { + "type": "string", + "format": "date-time", + "description": "When these credentials expire. The buyer must call update before this timestamp to rotate credentials." + }, + + "fulfillment:brokerUri": { + "type": "string", + "description": "MQTT broker URI (e.g. mqtts://iotcore.example.com:8883). Required for MQTTConnection." + }, + "fulfillment:topic": { + "type": "string", + "description": "MQTT topic filter (e.g. energy/meters/zone-a/#). Required for MQTTConnection." + }, + "fulfillment:qos": { + "type": "integer", + "description": "MQTT QoS level.", + "enum": [0, 1, 2] + }, + "fulfillment:clientId": { "type": "string" }, + "fulfillment:username": { "type": "string" }, + "fulfillment:password": { "type": "string" }, + "fulfillment:tlsCaCert": { "type": "string" }, + "fulfillment:sessionExpiry": { + "type": "string", + "description": "MQTT 5.0 Session Expiry Interval as ISO 8601 duration (e.g. PT24H)." + }, + + "fulfillment:bootstrapServers": { + "type": "string", + "description": "Comma-separated Kafka bootstrap server list. Required for KafkaConsumerCredentials." + }, + "fulfillment:topicName": { "type": "string" }, + "fulfillment:consumerGroupId": { "type": "string" }, + "fulfillment:saslMechanism": { + "type": "string", + "enum": ["PLAIN", "SCRAM-SHA-256", "SCRAM-SHA-512", "OAUTHBEARER"] + }, + "fulfillment:saslUsername": { "type": "string" }, + "fulfillment:saslPassword": { "type": "string" }, + "fulfillment:schemaRegistryUrl": { "type": "string", "format": "uri" }, + "fulfillment:schemaRegistryUsername": { "type": "string" }, + "fulfillment:schemaRegistryPassword": { "type": "string" }, + "fulfillment:startOffset": { + "type": "string", + "enum": ["latest", "earliest"] + }, + + "fulfillment:apiEndpoint": { + "type": "string", + "format": "uri", + "description": "Base URL of the REST API. Required for ApiCredential." + }, + "fulfillment:apiDocUrl": { "type": "string", "format": "uri" }, + "fulfillment:authScheme": { + "type": "string", + "enum": ["BEARER", "API_KEY", "BASIC", "OAUTH2_CLIENT_CREDENTIALS"] + }, + "fulfillment:bearerToken": { "type": "string" }, + "fulfillment:apiKey": { "type": "string" }, + "fulfillment:rateLimitRpm": { "type": "integer" }, + + "fulfillment:cloudProvider": { + "type": "string", + "enum": ["AWS_S3", "GCS", "AZURE_ADLS"] + }, + "fulfillment:accessType": { + "type": "string", + "description": "Credential type for object storage access. PRESIGNED_URL — single signed URL. STS_CREDENTIALS — temporary IAM credentials. SAS_TOKEN — Azure SAS.", + "enum": ["PRESIGNED_URL", "STS_CREDENTIALS", "SAS_TOKEN"] + }, + "fulfillment:bucket": { "type": "string" }, + "fulfillment:storagePrefix": { "type": "string" }, + "fulfillment:presignedUrl": { "type": "string", "format": "uri" }, + "fulfillment:accessKeyId": { "type": "string" }, + "fulfillment:secretAccessKey": { "type": "string" }, + "fulfillment:sessionToken": { "type": "string" }, + "fulfillment:sasToken": { "type": "string" }, + "fulfillment:storageRegion": { "type": "string" }, + "fulfillment:fileFormat": { "type": "string" }, + "fulfillment:partitionPattern": { "type": "string" } + } + } + } +} diff --git a/specification/schema/DatasetFulfillment/v1.1/vocab.jsonld b/specification/schema/DatasetFulfillment/v1.1/vocab.jsonld index 62d6069..eb20dd6 100644 --- a/specification/schema/DatasetFulfillment/v1.1/vocab.jsonld +++ b/specification/schema/DatasetFulfillment/v1.1/vocab.jsonld @@ -1,86 +1,11 @@ { "@context": { "@version": 1.1, - "schema": "https://schema.org/", "fulfillment": "https://beckn.org/schema/dataset-fulfillment#", "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#", - "rdfs": "http://www.w3.org/2000/01/rdf-schema#", - "xsd": "http://www.w3.org/2001/XMLSchema#" + "rdfs": "http://www.w3.org/2000/01/rdf-schema#" }, "@graph": [ - { - "@id": "fulfillment:DatasetFulfillment", - "@type": "rdfs:Class", - "rdfs:label": "DatasetFulfillment", - "rdfs:comment": "Access provisioning details for a fulfilled dataset order.", - "rdfs:subClassOf": { "@id": "schema:DataDownload" } - }, - { - "@id": "fulfillment:accessMethod", - "@type": "rdf:Property", - "rdfs:label": "accessMethod", - "rdfs:comment": "How the dataset is accessed: DOWNLOAD, API, STREAM, MQTT, KAFKA, DATA_LAKE, DATA_ROOM, or SFTP." - }, - { - "@id": "fulfillment:accessUrl", - "@type": "rdf:Property", - "rdfs:label": "accessUrl", - "rdfs:comment": "Signed or time-limited URL for accessing the dataset (DOWNLOAD only)." - }, - { - "@id": "fulfillment:accessStart", - "@type": "rdf:Property", - "rdfs:label": "accessStart", - "rdfs:comment": "Start of the access window (ISO 8601 date-time)." - }, - { - "@id": "fulfillment:accessEnd", - "@type": "rdf:Property", - "rdfs:label": "accessEnd", - "rdfs:comment": "End of the access window (ISO 8601 date-time). For streaming, use streamConnection.credentialExpiresAt." - }, - { - "@id": "fulfillment:format", - "@type": "rdf:Property", - "rdfs:label": "format", - "rdfs:comment": "File or message format delivered (e.g. Parquet, CSV, JSON, Avro, NDJSON)." - }, - { - "@id": "fulfillment:fileSizeBytes", - "@type": "rdf:Property", - "rdfs:label": "fileSizeBytes", - "rdfs:comment": "Approximate size of the delivered file in bytes (DOWNLOAD only)." - }, - { - "@id": "fulfillment:maxDownloads", - "@type": "rdf:Property", - "rdfs:label": "maxDownloads", - "rdfs:comment": "Maximum number of times the dataset can be downloaded (DOWNLOAD only)." - }, - { - "@id": "fulfillment:downloadsUsed", - "@type": "rdf:Property", - "rdfs:label": "downloadsUsed", - "rdfs:comment": "Number of downloads already used by the buyer (DOWNLOAD only)." - }, - { - "@id": "fulfillment:supportEmail", - "@type": "rdf:Property", - "rdfs:label": "supportEmail", - "rdfs:comment": "Support email for issues related to dataset access." - }, - { - "@id": "fulfillment:termsUrl", - "@type": "rdf:Property", - "rdfs:label": "termsUrl", - "rdfs:comment": "URL to the terms and conditions for dataset use." - }, - { - "@id": "fulfillment:attributionText", - "@type": "rdf:Property", - "rdfs:label": "attributionText", - "rdfs:comment": "Required attribution text for the dataset." - }, { "@id": "fulfillment:streamConnection", "@type": "rdf:Property", diff --git a/specification/schema/DatasetFulfillment/v1/context.jsonld b/specification/schema/DatasetFulfillment/v1/context.jsonld deleted file mode 100644 index 26dd566..0000000 --- a/specification/schema/DatasetFulfillment/v1/context.jsonld +++ /dev/null @@ -1,22 +0,0 @@ -{ - "@context": { - "@version": 1.1, - "schema": "https://schema.org/", - "fulfillment": "./vocab.jsonld#", - - "DatasetFulfillment": "fulfillment:DatasetFulfillment", - - "fulfillment:accessMethod": "fulfillment:accessMethod", - "fulfillment:accessUrl": "fulfillment:accessUrl", - "fulfillment:accessStart": "fulfillment:accessStart", - "fulfillment:accessEnd": "fulfillment:accessEnd", - "fulfillment:format": "fulfillment:format", - "fulfillment:fileSizeBytes": "fulfillment:fileSizeBytes", - "fulfillment:maxDownloads": "fulfillment:maxDownloads", - "fulfillment:downloadsUsed": "fulfillment:downloadsUsed", - "fulfillment:supportEmail": "fulfillment:supportEmail", - "fulfillment:termsUrl": "fulfillment:termsUrl", - "fulfillment:attributionText": "fulfillment:attributionText" - } -} - diff --git a/specification/schema/DatasetItem/README.md b/specification/schema/DatasetItem/README.md new file mode 100644 index 0000000..4a4f8e3 --- /dev/null +++ b/specification/schema/DatasetItem/README.md @@ -0,0 +1,31 @@ +# DatasetItem + +A dataset product in a Beckn catalog — extending [`schema:Dataset`](https://schema.org/Dataset) with Beckn-specific attributes for refresh cadence, granularity, sensitivity, quality flags, access method, and (in v1.1+) streaming transport metadata. + +Carried as `resourceAttributes`, `commitmentAttributes`, or `offerAttributes` in beckn messages where the resource being described is a dataset. + +## Versions + +| Version | Status | Highlights | +|---|---|---| +| [v1.0](./v1.0) | Stable | Base schema: identifier/name/temporal coverage, quality flags, four access methods (`INLINE`, `DOWNLOAD`, `DATA_ENCLAVE`, `OFF_CHANNEL`), inline `dataPayload`. | +| [v1.1](./v1.1) | Stable | Adds four streaming access methods (`MQTT`, `KAFKA`, `API`, `DATA_LAKE`) and a `dataset:streamMeta` sub-object for catalog-time stream topology metadata. Fully backward-compatible with v1.0. | + +## File layout + +Each version folder contains: + +- `attributes.yaml` — OpenAPI 3.1 component schema, the canonical structural definition +- `schema.json` — self-contained JSON Schema (draft 2020-12) for runtime validation +- `context.jsonld` — JSON-LD term mappings (each version inherits from the version below) +- `vocab.jsonld` — RDF property declarations +- `README.md` — version notes and examples + +Cross-version concerns (namespace prefixes, class IRI mappings, `rdfs:Class` declarations) live in the parent [`schema/context.jsonld`](../context.jsonld) and [`schema/vocab.jsonld`](../vocab.jsonld) and are inherited by each version. + +## Canonical URLs (after publish) + +``` +https://schema.beckn.io/DatasetItem/v1.0/{attributes.yaml,schema.json,context.jsonld,vocab.jsonld} +https://schema.beckn.io/DatasetItem/v1.1/{attributes.yaml,schema.json,context.jsonld,vocab.jsonld} +``` diff --git a/specification/schema/DatasetItem/v1.0/README.md b/specification/schema/DatasetItem/v1.0/README.md new file mode 100644 index 0000000..ad67464 --- /dev/null +++ b/specification/schema/DatasetItem/v1.0/README.md @@ -0,0 +1,74 @@ +# DatasetItem — v1.0 + +Base schema for describing a dataset product in a Beckn catalog. Extends [`schema:Dataset`](https://schema.org/Dataset) with Beckn-specific quality, sensitivity, and delivery attributes. + +## Required fields + +| Field | Notes | +|---|---| +| `schema:identifier` | Stable ID for the dataset. Buyers reference this in `confirm`. | +| `schema:name` | Human-readable name. | +| `schema:temporalCoverage` | ISO 8601 interval, e.g. `2026-01-01/2026-03-31`. | + +## Access methods + +`dataset:accessMethod` (enum): + +| Value | Meaning | Fulfillment | +|---|---|---| +| `INLINE` | Data is embedded in the beckn message via `dataset:dataPayload`. | Payload arrives in `on_confirm` / `on_status` `performanceAttributes`. | +| `DOWNLOAD` | Consumer fetches from a signed URL. | URL delivered in `DatasetFulfillment.fulfillment:accessUrl`. | +| `DATA_ENCLAVE` | Consumer accesses data inside a secure enclave. | Enclave endpoint and credentials negotiated off-channel. | +| `OFF_CHANNEL` | Delivery arranged outside the beckn network. | Provider and buyer coordinate directly. | + +## Catalog example — `DOWNLOAD` + +```json +{ + "@context": "https://schema.beckn.io/DatasetItem/v1.0/context.jsonld", + "@type": "DatasetItem", + "schema:identifier": "ds-rainprob-maharashtra-march-2026", + "schema:name": "Rainwater Probability — Maharashtra — March 2026", + "schema:temporalCoverage": "2026-03-01/2026-03-31", + "dataset:refreshType": "RECURRING", + "dataset:refreshFrequency": "P1D", + "dataset:granularity": "STATION_HOURLY", + "dataset:sensitivityLevel": "PUBLIC", + "dataset:accessMethod": "DOWNLOAD" +} +``` + +## Catalog example — `INLINE` + +```json +{ + "@context": "https://schema.beckn.io/DatasetItem/v1.0/context.jsonld", + "@type": "DatasetItem", + "schema:identifier": "ds-ami-meter-data-blr-zone-a-q1-2026", + "schema:name": "AMI Meter Data — Bengaluru Zone A — Q1 2026", + "schema:temporalCoverage": "2026-01-01/2026-03-31", + "dataset:accessMethod": "INLINE", + "dataset:dataPayload": { + "@context": "https://india-energy-stack.github.io/ies-accelerator/schemas/MeterData/v0.6/context.jsonld", + "@type": "MeterData" + } +} +``` + +## Quality flags + +`dataset:qualityFlags` is a sub-object aggregating standard QA/QC metrics: + +| Field | Description | +|---|---| +| `dataset:gapFilledPercent` | Percentage of records gap-filled by imputation. | +| `dataset:outlierRemovedPercent` | Percentage of records removed as outliers. | +| `dataset:latencyMinutes` | Typical latency between observation and availability. | +| `dataset:uptime99DayPercent` | Feed uptime over the trailing 99 days. | +| `dataset:validationMethod` | Standard or algorithm used (e.g. `IS-13731-2024`). | + +## Canonical URL + +``` +https://schema.beckn.io/DatasetItem/v1.0/context.jsonld +``` diff --git a/specification/schema/DatasetItem/v1/attributes.yaml b/specification/schema/DatasetItem/v1.0/attributes.yaml similarity index 100% rename from specification/schema/DatasetItem/v1/attributes.yaml rename to specification/schema/DatasetItem/v1.0/attributes.yaml diff --git a/specification/schema/DatasetItem/v1.0/context.jsonld b/specification/schema/DatasetItem/v1.0/context.jsonld new file mode 100644 index 0000000..94c9cb2 --- /dev/null +++ b/specification/schema/DatasetItem/v1.0/context.jsonld @@ -0,0 +1,32 @@ +{ + "@context": [ + "https://schema.beckn.io/schema/context.jsonld", + { + "@version": 1.1, + "refreshType": "dataset:refreshType", + "refreshFrequency": "dataset:refreshFrequency", + "granularity": "dataset:granularity", + "rowCountEstimate": "dataset:rowCountEstimate", + "columnCount": "dataset:columnCount", + "sensitivityLevel": "dataset:sensitivityLevel", + + "qualityFlags": "dataset:qualityFlags", + "gapFilledPercent": "dataset:gapFilledPercent", + "outlierRemovedPercent": "dataset:outlierRemovedPercent", + "latencyMinutes": "dataset:latencyMinutes", + "uptime99DayPercent": "dataset:uptime99DayPercent", + "validationMethod": "dataset:validationMethod", + + "accessMethod": "dataset:accessMethod", + "dataPayload": { + "@id": "dataset:dataPayload", + "@type": "@id" + }, + + "verticalRange": "dataset:verticalRange", + "dataType": "dataset:dataType", + "rawUpdateFrequency": "dataset:rawUpdateFrequency", + "latestRawDataAt": "dataset:latestRawDataAt" + } + ] +} diff --git a/specification/schema/DatasetItem/v1.0/schema.json b/specification/schema/DatasetItem/v1.0/schema.json new file mode 100644 index 0000000..711a9ac --- /dev/null +++ b/specification/schema/DatasetItem/v1.0/schema.json @@ -0,0 +1,109 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schema.beckn.io/DatasetItem/v1.0/schema.json", + "title": "DatasetItem", + "description": "Dataset metadata aligned with schema.org Dataset plus Beckn dataset extensions. Carried as resourceAttributes / commitmentAttributes / offerAttributes in beckn messages.", + "type": "object", + "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 via dataPayload. DOWNLOAD — consumer fetches from a URL. DATA_ENCLAVE — secure enclave access. OFF_CHANNEL — arranged outside beckn.", + "enum": ["INLINE", "DOWNLOAD", "DATA_ENCLAVE", "OFF_CHANNEL"] + }, + "dataset:dataPayload": { + "description": "Optional inline data payload. Carries the actual dataset content when dataset:accessMethod is INLINE. The @context URI must resolve to a schema describing the payload.", + "type": "object", + "additionalProperties": true, + "required": ["@context", "@type"], + "properties": { + "@context": { + "oneOf": [ + { "type": "string", "format": "uri" }, + { "type": "array", "items": { "type": "string", "format": "uri" } } + ] + }, + "@type": { "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" } + } + } + } +} diff --git a/specification/schema/DatasetItem/v1/vocab.jsonld b/specification/schema/DatasetItem/v1.0/vocab.jsonld similarity index 90% rename from specification/schema/DatasetItem/v1/vocab.jsonld rename to specification/schema/DatasetItem/v1.0/vocab.jsonld index 82f00b1..61dc488 100644 --- a/specification/schema/DatasetItem/v1/vocab.jsonld +++ b/specification/schema/DatasetItem/v1.0/vocab.jsonld @@ -2,21 +2,10 @@ "@context": { "@version": 1.1, "dataset": "https://beckn.org/schema/dataset#", - "schema": "https://schema.org/", "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#", - "rdfs": "http://www.w3.org/2000/01/rdf-schema#", - "xsd": "http://www.w3.org/2001/XMLSchema#" + "rdfs": "http://www.w3.org/2000/01/rdf-schema#" }, "@graph": [ - { - "@id": "dataset:DatasetItem", - "@type": "rdfs:Class", - "rdfs:label": "DatasetItem", - "rdfs:comment": "A dataset product in a Beckn catalog, extending schema.org Dataset.", - "rdfs:subClassOf": { - "@id": "schema:Dataset" - } - }, { "@id": "dataset:refreshType", "@type": "rdf:Property", @@ -127,4 +116,3 @@ } ] } - diff --git a/specification/schema/DatasetItem/v1.1/README.md b/specification/schema/DatasetItem/v1.1/README.md index 90cb5a1..8b682c9 100644 --- a/specification/schema/DatasetItem/v1.1/README.md +++ b/specification/schema/DatasetItem/v1.1/README.md @@ -1,6 +1,6 @@ # DatasetItem — v1.1 -Extends [v1](../v1/attributes.yaml) with streaming transport access methods and catalog-time stream metadata. Fully backward-compatible — all v1 fields and enum values are preserved unchanged. +Extends [v1.0](../v1.0/attributes.yaml) with streaming transport access methods and catalog-time stream metadata. Fully backward-compatible — all v1.0 fields and enum values are preserved unchanged. ## What's new in v1.1 diff --git a/specification/schema/DatasetItem/v1.1/context.jsonld b/specification/schema/DatasetItem/v1.1/context.jsonld index d59463d..7e8c151 100644 --- a/specification/schema/DatasetItem/v1.1/context.jsonld +++ b/specification/schema/DatasetItem/v1.1/context.jsonld @@ -1,40 +1,13 @@ { - "@context": { - "@version": 1.1, - "schema": "https://schema.org/", - "dataset": "./vocab.jsonld#", - - "DatasetItem": "dataset:DatasetItem", - - "refreshType": "dataset:refreshType", - "refreshFrequency": "dataset:refreshFrequency", - "granularity": "dataset:granularity", - "rowCountEstimate": "dataset:rowCountEstimate", - "columnCount": "dataset:columnCount", - "sensitivityLevel": "dataset:sensitivityLevel", - - "qualityFlags": "dataset:qualityFlags", - "gapFilledPercent": "dataset:gapFilledPercent", - "outlierRemovedPercent": "dataset:outlierRemovedPercent", - "latencyMinutes": "dataset:latencyMinutes", - "uptime99DayPercent": "dataset:uptime99DayPercent", - "validationMethod": "dataset:validationMethod", - - "accessMethod": "dataset:accessMethod", - "dataPayload": { - "@id": "dataset:dataPayload", - "@type": "@id" - }, - - "streamMeta": "dataset:streamMeta", - "streamProtocol": "dataset:streamProtocol", - "messageFormat": "dataset:messageFormat", - "updateFrequency": "dataset:updateFrequency", - "messageSchemaUrl": "dataset:messageSchemaUrl", - - "verticalRange": "dataset:verticalRange", - "dataType": "dataset:dataType", - "rawUpdateFrequency": "dataset:rawUpdateFrequency", - "latestRawDataAt": "dataset:latestRawDataAt" - } + "@context": [ + "https://schema.beckn.io/DatasetItem/v1.0/context.jsonld", + { + "@version": 1.1, + "streamMeta": "dataset:streamMeta", + "streamProtocol": "dataset:streamProtocol", + "messageFormat": "dataset:messageFormat", + "updateFrequency": "dataset:updateFrequency", + "messageSchemaUrl": "dataset:messageSchemaUrl" + } + ] } diff --git a/specification/schema/DatasetItem/v1.1/schema.json b/specification/schema/DatasetItem/v1.1/schema.json new file mode 100644 index 0000000..d16f9da --- /dev/null +++ b/specification/schema/DatasetItem/v1.1/schema.json @@ -0,0 +1,143 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schema.beckn.io/DatasetItem/v1.1/schema.json", + "title": "DatasetItem", + "description": "Dataset metadata aligned with schema.org Dataset plus Beckn dataset extensions. 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.", + "type": "object", + "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. INLINE/DOWNLOAD/DATA_ENCLAVE/OFF_CHANNEL from v1.0; v1.1 adds MQTT/KAFKA/API/DATA_LAKE — for streaming methods, credentials are provisioned 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 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 (e.g. 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)." + } + } + }, + "dataset:dataPayload": { + "description": "Optional inline data payload. Carries the actual dataset content when dataset:accessMethod is INLINE. The @context URI must resolve to a schema describing the payload.", + "type": "object", + "additionalProperties": true, + "required": ["@context", "@type"], + "properties": { + "@context": { + "oneOf": [ + { "type": "string", "format": "uri" }, + { "type": "array", "items": { "type": "string", "format": "uri" } } + ] + }, + "@type": { "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" } + } + } + } +} diff --git a/specification/schema/DatasetItem/v1.1/vocab.jsonld b/specification/schema/DatasetItem/v1.1/vocab.jsonld index 67002e9..0ab7fb0 100644 --- a/specification/schema/DatasetItem/v1.1/vocab.jsonld +++ b/specification/schema/DatasetItem/v1.1/vocab.jsonld @@ -2,105 +2,10 @@ "@context": { "@version": 1.1, "dataset": "https://beckn.org/schema/dataset#", - "schema": "https://schema.org/", "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#", - "rdfs": "http://www.w3.org/2000/01/rdf-schema#", - "xsd": "http://www.w3.org/2001/XMLSchema#" + "rdfs": "http://www.w3.org/2000/01/rdf-schema#" }, "@graph": [ - { - "@id": "dataset:DatasetItem", - "@type": "rdfs:Class", - "rdfs:label": "DatasetItem", - "rdfs:comment": "A dataset product in a Beckn catalog, extending schema.org Dataset.", - "rdfs:subClassOf": { - "@id": "schema:Dataset" - } - }, - { - "@id": "dataset:refreshType", - "@type": "rdf:Property", - "rdfs:label": "refreshType", - "rdfs:comment": "Refresh model for the dataset (STATIC, RECURRING, REAL_TIME)." - }, - { - "@id": "dataset:refreshFrequency", - "@type": "rdf:Property", - "rdfs:label": "refreshFrequency", - "rdfs:comment": "Refresh frequency when the dataset is recurring or real-time." - }, - { - "@id": "dataset:granularity", - "@type": "rdf:Property", - "rdfs:label": "granularity", - "rdfs:comment": "Observation unit granularity of the dataset (e.g. GRID_DAILY, STATION_HOURLY)." - }, - { - "@id": "dataset:rowCountEstimate", - "@type": "rdf:Property", - "rdfs:label": "rowCountEstimate", - "rdfs:comment": "Approximate number of rows in the dataset." - }, - { - "@id": "dataset:columnCount", - "@type": "rdf:Property", - "rdfs:label": "columnCount", - "rdfs:comment": "Number of columns in the dataset." - }, - { - "@id": "dataset:sensitivityLevel", - "@type": "rdf:Property", - "rdfs:label": "sensitivityLevel", - "rdfs:comment": "Sensitivity classification for the dataset (PUBLIC, INTERNAL, CONFIDENTIAL, etc.)." - }, - { - "@id": "dataset:qualityFlags", - "@type": "rdf:Property", - "rdfs:label": "qualityFlags", - "rdfs:comment": "Container for data quality metrics for the dataset." - }, - { - "@id": "dataset:gapFilledPercent", - "@type": "rdf:Property", - "rdfs:label": "gapFilledPercent", - "rdfs:comment": "Percentage of records gap-filled by imputation." - }, - { - "@id": "dataset:outlierRemovedPercent", - "@type": "rdf:Property", - "rdfs:label": "outlierRemovedPercent", - "rdfs:comment": "Percentage of records removed as outliers." - }, - { - "@id": "dataset:latencyMinutes", - "@type": "rdf:Property", - "rdfs:label": "latencyMinutes", - "rdfs:comment": "Typical latency in minutes between observation and availability." - }, - { - "@id": "dataset:uptime99DayPercent", - "@type": "rdf:Property", - "rdfs:label": "uptime99DayPercent", - "rdfs:comment": "Feed uptime percentage over the last 99 days." - }, - { - "@id": "dataset:validationMethod", - "@type": "rdf:Property", - "rdfs:label": "validationMethod", - "rdfs:comment": "Standard or algorithm used for dataset validation." - }, - { - "@id": "dataset:accessMethod", - "@type": "rdf:Property", - "rdfs:label": "accessMethod", - "rdfs:comment": "How the dataset is delivered: INLINE, DOWNLOAD, DATA_ENCLAVE, OFF_CHANNEL, MQTT, KAFKA, API, or DATA_LAKE. For streaming methods, credentials are provisioned in DatasetFulfillment after confirm." - }, - { - "@id": "dataset:dataPayload", - "@type": "rdf:Property", - "rdfs:label": "dataPayload", - "rdfs:comment": "Optional inline data payload carrying actual dataset content within the beckn message. A self-describing JSON-LD object whose @context resolves to the payload schema." - }, { "@id": "dataset:streamMeta", "@type": "rdf:Property", @@ -130,30 +35,6 @@ "@type": "rdf:Property", "rdfs:label": "messageSchemaUrl", "rdfs:comment": "URL to the message or file schema (JSON Schema, Avro schema, Protobuf descriptor, or OpenAPI spec). Consumers use this to configure deserializers." - }, - { - "@id": "dataset:verticalRange", - "@type": "rdf:Property", - "rdfs:label": "verticalRange", - "rdfs:comment": "Vertical extent of the dataset (e.g. surface, 0–2km AGL)." - }, - { - "@id": "dataset:dataType", - "@type": "rdf:Property", - "rdfs:label": "dataType", - "rdfs:comment": "Type or representation of the data (e.g. GriddedProbabilityField, TimeSeries)." - }, - { - "@id": "dataset:rawUpdateFrequency", - "@type": "rdf:Property", - "rdfs:label": "rawUpdateFrequency", - "rdfs:comment": "Frequency at which the underlying raw dataset is updated." - }, - { - "@id": "dataset:latestRawDataAt", - "@type": "rdf:Property", - "rdfs:label": "latestRawDataAt", - "rdfs:comment": "Timestamp of the latest raw data available that feeds this dataset." } ] } diff --git a/specification/schema/DatasetItem/v1/context.jsonld b/specification/schema/DatasetItem/v1/context.jsonld deleted file mode 100644 index 1bfd579..0000000 --- a/specification/schema/DatasetItem/v1/context.jsonld +++ /dev/null @@ -1,35 +0,0 @@ -{ - "@context": { - "@version": 1.1, - "schema": "https://schema.org/", - "dataset": "./vocab.jsonld#", - - "DatasetItem": "dataset:DatasetItem", - - "refreshType": "dataset:refreshType", - "refreshFrequency": "dataset:refreshFrequency", - "granularity": "dataset:granularity", - "rowCountEstimate": "dataset:rowCountEstimate", - "columnCount": "dataset:columnCount", - "sensitivityLevel": "dataset:sensitivityLevel", - - "qualityFlags": "dataset:qualityFlags", - "gapFilledPercent": "dataset:gapFilledPercent", - "outlierRemovedPercent": "dataset:outlierRemovedPercent", - "latencyMinutes": "dataset:latencyMinutes", - "uptime99DayPercent": "dataset:uptime99DayPercent", - "validationMethod": "dataset:validationMethod", - - "accessMethod": "dataset:accessMethod", - "dataPayload": { - "@id": "dataset:dataPayload", - "@type": "@id" - }, - - "verticalRange": "dataset:verticalRange", - "dataType": "dataset:dataType", - "rawUpdateFrequency": "dataset:rawUpdateFrequency", - "latestRawDataAt": "dataset:latestRawDataAt" - } -} - diff --git a/specification/schema/context.jsonld b/specification/schema/context.jsonld new file mode 100644 index 0000000..db9ba20 --- /dev/null +++ b/specification/schema/context.jsonld @@ -0,0 +1,15 @@ +{ + "@context": { + "@version": 1.1, + "@protected": true, + "schema": "https://schema.org/", + "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#", + "rdfs": "http://www.w3.org/2000/01/rdf-schema#", + "xsd": "http://www.w3.org/2001/XMLSchema#", + "dataset": "https://beckn.org/schema/dataset#", + "fulfillment": "https://beckn.org/schema/dataset-fulfillment#", + + "DatasetItem": "dataset:DatasetItem", + "DatasetFulfillment": "fulfillment:DatasetFulfillment" + } +} diff --git a/specification/schema/vocab.jsonld b/specification/schema/vocab.jsonld new file mode 100644 index 0000000..5969f6d --- /dev/null +++ b/specification/schema/vocab.jsonld @@ -0,0 +1,27 @@ +{ + "@context": { + "@version": 1.1, + "schema": "https://schema.org/", + "dataset": "https://beckn.org/schema/dataset#", + "fulfillment": "https://beckn.org/schema/dataset-fulfillment#", + "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#", + "rdfs": "http://www.w3.org/2000/01/rdf-schema#", + "xsd": "http://www.w3.org/2001/XMLSchema#" + }, + "@graph": [ + { + "@id": "dataset:DatasetItem", + "@type": "rdfs:Class", + "rdfs:label": "DatasetItem", + "rdfs:comment": "A dataset product in a Beckn catalog, extending schema.org Dataset. Carried as resourceAttributes / commitmentAttributes / offerAttributes in beckn messages.", + "rdfs:subClassOf": { "@id": "schema:Dataset" } + }, + { + "@id": "fulfillment:DatasetFulfillment", + "@type": "rdfs:Class", + "rdfs:label": "DatasetFulfillment", + "rdfs:comment": "Access provisioning details for a fulfilled dataset order — delivery method plus the credentials or URLs required to retrieve the data. Carried as performanceAttributes / fulfillmentAttributes in beckn messages.", + "rdfs:subClassOf": { "@id": "schema:DataDownload" } + } + ] +}