|
1 | | ---- |
2 | | -title: Schema registry specification version 0.1.0 |
3 | | ---- |
4 | 1 |
|
5 | | -<!-- Table of contents: |
6 | | -* The generated Toc will be an unordered list |
7 | | -{:toc} --> |
| 2 | +<!-- Include auto-generated md from openAPI yaml file for API specification itself --> |
8 | 3 |
|
9 | | -# Schema registry version 0.1.0 |
| 4 | +[OAD(./docs/specification.yaml)] |
10 | 5 |
|
11 | | -<!-- Table of contents: |
12 | 6 |
|
13 | | -[TOC] --> |
14 | | - |
15 | | -## Specification version |
16 | | - |
17 | | -This specification is in **DRAFT** form. This is **NOT YET AN APPROVED GA4GH specification**. This document is **formal technical explanation for implementers**. See also: |
18 | | - |
19 | | -- [Architectural decision record](decision_record.md), a chronological record of spec decisions. |
20 | | - |
21 | | -## Introduction |
22 | | - |
23 | | -GA4GH Workstreams gather experts from a particular area of interest and develop standards, frameworks and tools. Workstreams operate independently and often define different vocabulary and data representation (schema) standards. This presents challenges when bringing together products from different workstreams and hinders adoption of GA4GH products. |
24 | | - |
25 | | -A schema defines the structure used to store or exchange data. It is often an implementation of a data model either implicitly or explicitly but usually includes optimizations/restrictions that are not relevant to the data model. |
26 | | - |
27 | | -A GA4GH Schema Registry is an online location where the GA4GH community can find schemas that are in use within and/or recommended by the GA4GH community. |
28 | | - |
29 | | -The goal of the schema registry specification is to provide a standard for representation and exchange of schemas. |
30 | | - |
31 | | -## Use cases |
32 | | - |
33 | | -To be added |
34 | | - |
35 | | -## Definitions of key terms |
36 | | - |
37 | | -### General terms |
38 | | - |
39 | | -- **Namespace**: The name of a user or organization that owns schemas. Analogous to a github user or organization name. The namespace forms part of the registry path for a schema. |
40 | | -- **Schema**: A document that defines the structure used to store or exchange data. |
41 | | -- **Schema Registry**: A web location where schemas are stored. |
42 | | -- **Semantic Version**: A string like, `MAJOR.MINOR.PATCH` (e.g. `0.4.3`) that uses following the semantic versioning standard, used to version a schema. |
43 | | -- **Registry path**: A name used to identify a schema, consisting of the namespace and schema name, like `{namespace}/{schema_name}`. Analogous to a repository name on GitHub. Schema registry paths uniquely identify a particular schema within a given implementation/provider. |
44 | | - |
45 | | - |
46 | | -## 1. API Specification |
47 | | - |
48 | | -### List schemas within a namespace |
49 | | - |
50 | | -**Endpoint:** `GET /schemas/{namespace}/?attr1=val1&lifecycle_stage=released` |
51 | | - |
52 | | -#### Params: |
53 | | - |
54 | | -- {namespace}: as above |
55 | | -- {attr1}: query key-value pairs provided will filter |
56 | | - |
57 | | -#### Response: 200 |
58 | | - |
59 | | -Content: A list of schemas within a namespace. |
60 | | - |
61 | | -Example: |
62 | | - |
63 | | -``` |
64 | | -{ |
65 | | - "namespace": "some-namespace", |
66 | | - "schemas": [ |
67 | | - { |
68 | | - "schema_name": "my_schema_name", |
69 | | - "latest_version": "0.5.4", |
70 | | - "maintainer": ["...", "...."], |
71 | | - "lifecycle_stage": "released" |
72 | | - } |
73 | | - ] |
74 | | -} |
75 | | -``` |
76 | | - |
77 | | ---- |
78 | | - |
79 | | -### Get a list of versions for a given schema |
80 | | - |
81 | | -**Endpoint:** `GET /schemas/{namespace}/{schema_name}/versions` |
82 | | - |
83 | | -#### Params: |
84 | | - |
85 | | -- `{namespace}`: as above |
86 | | -- `{schema_name}`: as above |
87 | | - |
88 | | -#### Response: 200 |
89 | | - |
90 | | -Content: Object with `schema_name` and `versions`, containing an array of objects holding version and label information. |
91 | | - |
92 | | -Example: |
93 | | - |
94 | | -```json |
95 | | -{ |
96 | | - "schema_name": "some-schema-name", |
97 | | - "versions": [ |
98 | | - { |
99 | | - "version": "0.1.0", |
100 | | - "status": "current|deprecated|latest", |
101 | | - "release_date": "2024-10-31T12:34:56Z", |
102 | | - "contributors": ["The DaMaSC working group", "..."], |
103 | | - "release_notes": "Markdown Text" |
104 | | - } |
105 | | - ] |
106 | | -} |
107 | | -``` |
108 | | - |
109 | | ---- |
110 | | - |
111 | | -### Get content of a schema |
112 | | - |
113 | | -**Endpoint:** `GET /schemas/{namespace}/{schema_name}/versions/{semantic_version}` |
114 | | - |
115 | | -#### Params: |
116 | | - |
117 | | -- `{semantic_version}`: A string indicating `MAJOR.MINOR.PATCH` version following semver (e.g., `"0.17.4"`) |
118 | | -- `{namespace}`: A string indicating the organization/user who owns this schema (e.g., `"ga4gh"` for GA4GH-sponsored/approved schemas) |
119 | | -- `{schema_name}`: Name of this schema, following the same naming rules as GitHub repositories |
120 | | - |
121 | | -#### Response: 200 |
122 | | - |
123 | | -Content: The JSON Schema. |
124 | | - |
125 | | -If `{semantic_version} == "latest"`, this endpoint should return the maximum version number currently in the database. |
126 | | - |
127 | | ---- |
128 | | - |
129 | | -### Get a list of namespaces |
130 | | - |
131 | | -**Endpoint:** `GET /namespaces` |
132 | | - |
133 | | -#### Params: |
134 | | - |
135 | | -- None |
136 | | - |
137 | | -#### Response: 200 |
138 | | - |
139 | | -Content: A list of namespaces hosted by this server. |
140 | | - |
141 | | -Example: |
142 | | - |
143 | | -```json |
144 | | -{ |
145 | | - "server": "service.url.org", |
146 | | - "namespaces": [ |
147 | | - { |
148 | | - "namespace_name": "my_namespace_name", |
149 | | - "latest_version": "0.5.4", |
150 | | - "contact_url": "http://..." |
151 | | - } |
152 | | - ] |
153 | | -} |
154 | | -``` |
0 commit comments