openapi: 3.1.0
info:
contact:
name: Contact Us
url: https://data.world/company/contact-us
termsOfService: https://data.world/terms-policies
title: data.world Public catalog relationships datasets API
version: '0'
description: Manage relationships between catalog resources
servers:
- url: /v0
security:
- bearerAuth: []
tags:
- name: datasets
paths:
/datasets/{owner}:
get:
description: 'List datasets that the currently authenticated user has access to, for the specified owner; when the
dataset is open, private (but discoverable by the authenticated user) or the authenticated user is a
contributor with discover visibility'
operationId: getDatasetsByOwner
parameters:
- in: query
name: fields
schema:
type: string
- in: path
name: owner
required: true
schema:
type: string
- description: Number of results to return
in: query
name: limit
schema:
type: integer
format: int32
default: 10
maximum: 100
minimum: 1
- description: A token supplied by the previous response to retrieve the next page of results
in: query
name: next
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedDatasetResults'
description: default response
summary: List datasets for a specified owner
tags:
- datasets
post:
description: Create a new dataset.
operationId: createDataset
parameters:
- in: path
name: owner
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetCreateRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDatasetResponse'
description: Dataset created successfully.
summary: Create a dataset
tags:
- datasets
/datasets/{owner}/{id}:
delete:
description: 'Delete a dataset and associated data. This operation cannot be undone, but you may recreate the dataset
using the same id.'
operationId: deleteDataset
parameters:
- in: path
name: owner
required: true
schema:
type: string
- in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessMessage'
description: default response
summary: Delete a dataset
tags:
- datasets
get:
description: 'Retrieve a dataset. The definition of the dataset will be returned, not its data. Use
`GET:/download/{owner}/{id}` or `GET:/file_download/{owner}/{id}/{file}` to retrieve the original files
content, or `POST:/sql/{owner}/{id}` or `POST:/sparql/{owner}/{id}` to query the data.'
operationId: getDataset
parameters:
- in: path
name: owner
required: true
schema:
type: string
- in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetSummaryResponse'
description: default response
summary: Retrieve a dataset
tags:
- datasets
patch:
description: 'Update an existing dataset. Only elements included in the request will be updated. All omitted elements
will remain untouched. Requesting change in a list replaces the entire list. Requesting an element to be
null deletes all values on the element.'
operationId: patchDataset
parameters:
- in: path
name: owner
required: true
schema:
type: string
- in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetPatchRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessMessage'
description: default response
summary: Update a dataset
tags:
- datasets
put:
description: 'Create or replace a dataset with a given id. If a dataset exists with the same id, this call will reset
such dataset and all the data contained in it.'
operationId: replaceDataset
parameters:
- in: path
name: owner
required: true
schema:
type: string
- in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetPutRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessMessage'
description: default response
summary: Create / Replace a dataset
tags:
- datasets
/datasets/{owner}/{id}/sync/{filename}:
get:
operationId: syncFileViaGet
parameters:
- in: path
name: owner
required: true
schema:
type: string
minLength: 1
- in: path
name: id
required: true
schema:
type: string
minLength: 1
- in: path
name: filename
required: true
schema:
type: string
minLength: 1
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessMessage'
description: default response
summary: Fetch latest file from source and update dataset — via GET, for convenience.
tags:
- datasets
post:
operationId: syncFile
parameters:
- in: path
name: owner
required: true
schema:
type: string
minLength: 1
- in: path
name: id
required: true
schema:
type: string
minLength: 1
- in: path
name: filename
required: true
schema:
type: string
minLength: 1
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessMessage'
description: default response
summary: Fetch latest file from source and update dataset.
tags:
- datasets
/datasets/{owner}/{id}/v/{versionId}:
get:
description: Retrieve a version of a dataset. The definition of the dataset will be returned, not its data.
operationId: getDatasetByVersion
parameters:
- in: path
name: owner
required: true
schema:
type: string
- in: path
name: id
required: true
schema:
type: string
- in: path
name: versionId
required: true
schema:
type: string
minLength: 1
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetSummaryResponse'
description: default response
summary: Retrieve a dataset version
tags:
- datasets
/download/{owner}/{id}:
get:
description: 'Download a .zip file containing all files within a dataset as originally uploaded. Prefer `POST:/sql` or
`POST:/sparql` for retrieving clean and structured data.'
operationId: downloadDataset
parameters:
- in: path
name: owner
required: true
schema:
type: string
- in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/zip: {}
description: default response
summary: Download a dataset
tags:
- datasets
components:
schemas:
QueryExecutionDto:
type: object
properties:
query:
type: string
maxLength: 10000
minLength: 1
required:
- query
FileSourceCreateRequest:
type: object
properties:
authorization:
$ref: '#/components/schemas/WebAuthorization'
credentials:
$ref: '#/components/schemas/WebCredentials'
dataTables:
type: object
additionalProperties:
$ref: '#/components/schemas/QueryExecutionDto'
databaseMetadataSpec:
$ref: '#/components/schemas/DatabaseMetadataSpecDto'
databaseSource:
$ref: '#/components/schemas/DatabaseSourceReference'
dwccSpec:
$ref: '#/components/schemas/DwccSpecDto'
expandArchive:
type: boolean
method:
type: string
enum:
- GET
- POST
oauthToken:
$ref: '#/components/schemas/OauthTokenReference'
requestEntity:
type: string
maxLength: 10000
minLength: 0
requestHeaders:
type: object
additionalProperties:
type: string
tableSpec:
$ref: '#/components/schemas/SingleTableMetadataSpecDto'
url:
type: string
format: uri
useDwCredentials:
type: boolean
viewRequest:
$ref: '#/components/schemas/ViewRequestDto'
FileSummaryResponse:
type: object
properties:
created:
type: string
format: date-time
createdBy:
type: string
description:
type: string
maxLength: 120
minLength: 1
labels:
type: array
items:
type: string
name:
type: string
maxLength: 128
minLength: 1
pattern: ^[^/]+$
sizeInBytes:
type: integer
format: int64
source:
$ref: '#/components/schemas/FileSourceSummaryResponse'
updated:
type: string
format: date-time
updatedBy:
type: string
required:
- created
- name
- updated
FileCreateRequest:
type: object
properties:
description:
type: string
maxLength: 120
minLength: 1
labels:
type: array
items:
type: string
name:
type: string
maxLength: 128
minLength: 1
pattern: ^[^/]+$
source:
$ref: '#/components/schemas/FileSourceCreateRequest'
required:
- name
- source
DatabaseSourceReference:
type: object
properties:
id:
type: string
format: uuid
owner:
type: string
required:
- id
- owner
DatasetStatistics:
type: object
properties:
columnCount:
type: integer
format: int32
fileCount:
type: integer
format: int32
tableCount:
type: integer
format: int32
SimpleDataset:
allOf:
- $ref: '#/components/schemas/SimpleResource'
- type: object
properties:
description:
type: string
maxLength: 120
minLength: 0
id:
type: string
license:
type: string
enum:
- Public Domain, PDDL, CC-0, CC-BY, CDLA-Permissive-1.0, CC-BY-IGO, CC-BY 3.0, CC-BY 3.0 AU, CC-BY 3.0 IGO, CC-BY-SA, CC-BY-SA 3.0, CDLA-Sharing-1.0, CC BY-NC, CC BY-ND, CC BY-ND 3.0, CC-BY 3.0 NZ, CC-BY-NC 3.0, CC BY-NC-ND, CC-BY-NC-SA 3.0, CC-BY-SA 3.0 NZ, CC-BY-NC-SA 3.0 NZ, CC-BY-NC 3.0 NZ, CC-BY-NC-ND-NZ-3.0, CC BY-NC-SA, Italian-ODL, MIT License, OGL, OGL-Canada, OGL-Nova Scotia, OGL-UK, OSODL, ODC-BY, ODC-ODbL, Other
owner:
type: string
summary:
type: string
maxLength: 25000
minLength: 0
tags:
type: array
items:
type: string
title:
type: string
maxLength: 60
minLength: 1
type:
type: string
enum:
- dataset
- project
visibility:
type: string
enum:
- OPEN, PRIVATE
required:
- id
- owner
WebCredentials:
type: object
properties:
password:
type: string
maxLength: 2048
minLength: 0
user:
type: string
maxLength: 2048
minLength: 0
required:
- user
SingleTableMetadataSpecDto:
type: object
properties:
database:
type: string
schema:
type: string
table:
type: string
tableType:
type: string
enum:
- EXTRACT
- VIRTUAL
DatasetPatchRequest:
type: object
properties:
assetStatusIri:
type: string
autoSyncInterval:
type: string
description: Interval in which files should be synced
enum:
- NEVER
- HOURLY
- DAILY
- WEEKLY
description:
type: string
license:
type: string
enum:
- Public Domain, PDDL, CC-0, CC-BY, CDLA-Permissive-1.0, CC-BY-IGO, CC-BY 3.0, CC-BY 3.0 AU, CC-BY 3.0 IGO, CC-BY-SA, CC-BY-SA 3.0, CDLA-Sharing-1.0, CC BY-NC, CC BY-ND, CC BY-ND 3.0, CC-BY 3.0 NZ, CC-BY-NC 3.0, CC BY-NC-ND, CC-BY-NC-SA 3.0, CC-BY-SA 3.0 NZ, CC-BY-NC-SA 3.0 NZ, CC-BY-NC 3.0 NZ, CC-BY-NC-ND-NZ-3.0, CC BY-NC-SA, Italian-ODL, MIT License, OGL, OGL-Canada, OGL-Nova Scotia, OGL-UK, OSODL, ODC-BY, ODC-ODbL, Other
properties:
type: object
additionalProperties:
$ref: '#/components/schemas/JsonNode'
summary:
type: string
tags:
type: array
description: Tags included in a PATCH request will replace all previous tags.
items:
type: string
description: Tags included in a PATCH request will replace all previous tags.
title:
type: string
maxLength: 60
minLength: 1
visibility:
type: string
enum:
- OPEN, PRIVATE
FileSourceSummaryResponse:
type: object
properties:
authorization:
$ref: '#/components/schemas/WebAuthorization'
credentials:
$ref: '#/components/schemas/WebCredentials'
dataTables:
type: object
additionalProperties:
$ref: '#/components/schemas/QueryExecutionDto'
databaseMetadataSpec:
$ref: '#/components/schemas/DatabaseMetadataSpecDto'
databaseSource:
$ref: '#/components/schemas/DatabaseSourceReference'
dwccSpec:
$ref: '#/components/schemas/DwccSpecDto'
expandArchive:
type: boolean
lastSyncFailure:
type: string
format: date-time
lastSyncStart:
type: string
format: date-time
lastSyncSuccess:
type: string
format: date-time
mediaType:
type: string
mediaTypeLocked:
type: boolean
method:
type: string
enum:
- GET
- POST
oauthToken:
$ref: '#/components/schemas/OauthTokenReference'
requestEntity:
type: string
maxLength: 10000
minLength: 0
requestHeaders:
type: object
additionalProperties:
type: string
syncStatus:
type: string
enum:
- NEW
- INPROGRESS
- OK
- SYSTEMERROR
syncSummary:
type: string
tableSpec:
$ref: '#/components/schemas/SingleTableMetadataSpecDto'
url:
type: string
format: uri
useDwCredentials:
type: boolean
viewRequest:
$ref: '#/components/schemas/ViewRequestDto'
required:
- syncStatus
OauthTokenReference:
type: object
properties:
id:
type: string
format: uuid
owner:
type: string
site:
type: string
required:
- id
- owner
- site
AssetStatus:
type: object
properties:
assetStatusLabel:
type: string
dispositionLabel:
type: string
DwccSpecDto:
type: object
properties:
databaseId:
type: string
metadataToExclude:
type: array
items:
type: string
sourceDatabase:
type: string
sourceSchemas:
type: array
items:
type: string
targetCatalog:
type: string
DatasetSummaryResponse:
type: object
properties:
accessLevel:
type: string
enum:
- NONE, DISCOVER, READ, WRITE, ADMIN
assetStatus:
$ref: '#/components/schemas/AssetStatus'
created:
type: string
format: date-time
datasetStatistics:
$ref: '#/components/schemas/DatasetStatistics'
description: Describes number of files, tables, and columns in the dataset
description:
type: string
maxLength: 120
minLength: 0
dois:
type: array
items:
$ref: '#/components/schemas/Doi'
files:
type: array
items:
$ref: '#/components/schemas/FileSummaryResponse'
id:
type: string
isProject:
type: boolean
license:
type: string
enum:
- Public Domain, PDDL, CC-0, CC-BY, CDLA-Permissive-1.0, CC-BY-IGO, CC-BY 3.0, CC-BY 3.0 AU, CC-BY 3.0 IGO, CC-BY-SA, CC-BY-SA 3.0, CDLA-Sharing-1.0, CC BY-NC, CC BY-ND, CC BY-ND 3.0, CC-BY 3.0 NZ, CC-BY-NC 3.0, CC BY-NC-ND, CC-BY-NC-SA 3.0, CC-BY-SA 3.0 NZ, CC-BY-NC-SA 3.0 NZ, CC-BY-NC 3.0 NZ, CC-BY-NC-ND-NZ-3.0, CC BY-NC-SA, Italian-ODL, MIT License, OGL, OGL-Canada, OGL-Nova Scotia, OGL-UK, OSODL, ODC-BY, ODC-ODbL, Other
linkedDatasets:
type: array
items:
$ref: '#/components/schemas/LinkedDatasetSummaryResponse'
writeOnly: true
owner:
type: string
properties:
type: object
additionalProperties:
$ref: '#/components/schemas/StringOrArray'
description: All properties of the resource that are associated with a metadata presentation. Key is the IRI of the property. Value is the value of the property.
similarResources:
type: array
description: Similar datasets with the same owner
items:
oneOf:
- $ref: '#/components/schemas/SimpleDataset'
status:
type: string
enum:
- NEW, INPROGRESS, LOADED, SYSTEMERROR
summary:
type: string
maxLength: 25000
minLength: 0
tags:
type: array
items:
type: string
title:
type: string
maxLength: 60
minLength: 1
updated:
type: string
format: date-time
version:
type: string
versionDois:
type: array
items:
$ref: '#/components/schemas/Doi'
visibility:
type: string
enum:
- OPEN, PRIVATE
required:
- accessLevel
- created
- id
- isProject
- owner
- status
- title
- updated
- version
- visibility
WebAuthorization:
type: object
properties:
credentials:
type: string
maxLength: 2048
minLength: 1
type:
type: string
maxLength: 50
minLength: 0
required:
- type
PaginatedDatasetResults:
type: object
properties:
count:
type: integer
format: int32
minimum: 0
nextPageToken:
type: string
records:
type: array
items:
$ref: '#/components/schemas/DatasetSummaryResponse'
required:
- count
- records
LinkedDatasetSummaryResponse:
type: object
properties:
accessLevel:
type: string
enum:
- NONE, DISCOVER, READ, WRITE, ADMIN
created:
type: string
format: date-time
description:
type: string
maxLength: 120
minLength: 0
id:
type: string
license:
type: string
enum:
- Public Domain, PDDL, CC-0, CC-BY, CDLA-Permissive-1.0, CC-BY-IGO, CC-BY 3.0, CC-BY 3.0 AU, CC-BY 3.0 IGO, CC-BY-SA, CC-BY-SA 3.0, CDLA-Sharing-1.0, CC BY-NC, CC BY-ND, CC BY-ND 3.0, CC-BY 3.0 NZ, CC-BY-NC 3.0, CC BY-NC-ND, CC-BY-NC-SA 3.0, CC-BY-SA 3.0 NZ, CC-BY-NC-SA 3.0 NZ, CC-BY-NC 3.0 NZ, CC-BY-NC-ND-NZ-3.0, CC BY-NC-SA, Italian-ODL, MIT License, OGL, OGL-Canada, OGL-Nova Scotia, OGL-UK, OSODL, ODC-BY, ODC-ODbL, Other
owner:
type: string
summary:
type: string
maxLength: 25000
minLength: 0
tags:
type: array
items:
type: string
title:
type: string
maxLength: 60
minLength: 1
updated:
type: string
format: date-time
version:
type: string
visibility:
type: string
enum:
- OPEN, PRIVATE
required:
- accessLevel
- created
- id
- owner
- title
- updated
- visibility
StringOrArray:
oneOf:
- type: string
- type: array
items:
type: string
DatabaseMetadataSpecDto:
type: object
properties:
tableSpecs:
type: array
items:
$ref: '#/components/schemas/TableMetadataSpecDto'
maxItems: 100
minItems: 0
TableMetadataSpecDto:
type: object
properties:
database:
type: string
schema:
type: string
tablePrefixes:
type: array
items:
type: string
tableTypes:
type: array
items:
type: string
enum:
- TABLE
- EXTERNAL_TABLE
- VIEW
tables:
type: array
items:
type: string
ViewRequestDto:
type: object
properties:
baseAgentId:
type: string
baseDatasetId:
type: string
queryId:
type: string
format: uuid
queryName:
type: string
queryText:
type: string
maxLength: 10000
minLength: 1
queryType:
type: string
enum:
- SPARQL
- SQL
runAsAgentId:
type: string
targetAgentId:
type: string
targetDatasetId:
type: string
required:
- baseAgentId
- baseDatasetId
- queryName
- queryType
- runAsAgentId
- targetAgentId
- targetDatasetId
DatasetCreateRequest:
type: object
properties:
assetStatusIri:
type: string
autoSyncInterval:
type: string
description: Interval in which files should be synced
enum:
- NEVER
- HOURLY
- DAILY
- WEEKLY
description:
type: string
maxLength: 120
minLength: 0
files:
type: array
items:
$ref: '#/components/schemas/FileCreateRequest'
license:
type: string
enum:
- Public Domain, PDDL, CC-0, CC-BY, CDLA-Permissive-1.0, CC-BY-IGO, CC-BY 3.0, CC-BY 3.0 AU, CC-BY 3.0 IGO, CC-BY-SA, CC-BY-SA 3.0, CDLA-Sharing-1.0, CC BY-NC, CC BY-ND, CC BY-ND 3.0, CC-BY 3.0 NZ, CC-BY-NC 3.0, CC BY-NC-ND, CC-BY-NC-SA 3.0, CC-BY-SA 3.0 NZ, CC-BY-NC-SA 3.0 NZ, CC-BY-NC 3.0 NZ, CC-BY-NC-ND-NZ-3.0, CC BY-NC-SA, Italian-ODL, MIT License, OGL, OGL-Canada, OGL-Nova Scotia, OGL-UK, OSODL, ODC-BY, ODC-ODbL, Other
properties:
type: object
additionalProperties:
$ref: '#/components/schemas/StringOrArray'
description: Create/update any property that is associated with a metadata presentation. Key is the IRI of the property. Value is the intended value of the property.
summary:
type: string
maxLength: 25000
minLength: 0
tags:
type: array
items:
type: string
title:
type: string
maxLength: 60
minLength: 1
visibility:
type: string
enum:
- OPEN, PRIVATE
required:
- title
- visibility
JsonNode: {}
CreateDatasetResponse:
type: object
properties:
message:
type: string
maxLength: 256
minLength: 0
uri:
type: string
format: uri
required:
- uri
SimpleResource:
type: object
discriminator:
mapping:
dataset: '#/components/schemas/SimpleDataset'
project: '#/components/schemas/SimpleDataset'
propertyName: type
properties:
type:
type: string
description: The type of the resource
enum:
- dataset
- project
Doi:
type: object
properties:
created:
type: string
format: date-time
doi:
type: string
required:
- created
- doi
DatasetPutRequest:
type: object
properties:
assetStatusIri:
type: string
description:
type: string
maxLength: 120
minLength: 0
license:
type: string
enum:
- Public Domain, PDDL, CC-0, CC-BY, CDLA-Permissive-1.0, CC-BY-IGO, CC-BY 3.0, CC-BY 3.0 AU, CC-BY 3.0 IGO, CC-BY-SA, CC-BY-SA 3.0, CDLA-Sharing-1.0, CC BY-NC, CC BY-ND, CC BY-ND 3.0, CC-BY 3.0 NZ, CC-BY-NC 3.0, CC BY-NC-ND, CC-BY-NC-SA 3.0, CC-BY-SA 3.0 NZ, CC-BY-NC-SA 3.0 NZ, CC-BY-NC 3.0 NZ, CC-BY-NC-ND-NZ-3.0, CC BY-NC-SA, Italian-ODL, MIT License, OGL, OGL-Canada, OGL-Nova Scotia, OGL-UK, OSODL, ODC-BY, ODC-ODbL, Other
properties:
type: object
additionalProperties:
$ref: '#/components/schemas/StringOrArray'
description: Create/update any property that is associated with a metadata presentation. Key is the IRI of the property. Value is the intended value of the property.
summary:
type: string
maxLength: 25000
minLength: 0
tags:
type: array
items:
type: string
title:
type: string
maxLength: 60
minLength: 1
visibility:
type: string
enum:
- OPEN, PRIVATE
required:
- title
- visibility
SuccessMessage:
type: object
properties:
message:
type: string
maxLength: 256
minLength: 0
securitySchemes:
bearerAuth:
bearerFormat: JWT
scheme: bearer
type: http