You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit f8a8263
Browse filesBrowse the repository at this point in the historyBrowse files
A minimal, idiomatic Python library for working with **GTS** ([Global Type System](https://github.com/gts-spec/gts-spec)) identifiers and JSON/JSON Schema artifacts.
5
+
A minimal, idiomatic Python library for working with **GTS** ([Global Type System](https://github.com/GlobalTypeSystem/gts-spec)) identifiers and JSON/JSON Schema artifacts.
6
6
7
-
Current supported GTS spec version: `0.15.0`. Conformance CI pins the released gts-spec`v0.15.0`in [`.gts-spec-version`](.gts-spec-version) and the `.gts-spec` submodule; run`make update-spec` to check the pinned release out. The 0.15 breaking change is the [safe regular-expression profile](gts/README.md#regular-expressions).
7
+
Targets gts-spec [v0.17.0](https://github.com/GlobalTypeSystem/gts-spec/releases/tag/v0.17.0) — recorded in [`.gts-spec-version`](.gts-spec-version) and pinned by the `.gts-spec` submodule. Run`make update-spec` to check the pinned release out.
8
8
9
9
## Roadmap
10
10
@@ -29,14 +29,16 @@ Featureset:
29
29
30
30
See details in [gts/README.md](gts/README.md)
31
31
32
-
Other GTS spec [Reference Implementation](https://github.com/globaltypesystem/gts-spec/blob/main/README.md#9-reference-implementation-recommendations) recommended features support:
32
+
Other GTS spec [Reference Implementation](https://github.com/GlobalTypeSystem/gts-spec/blob/main/README.md#9-reference-implementation-recommendations) recommended features support:
33
33
34
34
-[x]**In-memory entities registry** - simple GTS entities registry with optional GTS references validation on entity registration
35
35
-[x]**CLI** - command-line interface for all GTS operations
36
36
-[x]**Web server** - a non-production web-server with REST API for the operations processing and testing
37
-
-[x]**x-gts-ref support** - to support special GTS entity reference annotation in schemas
-[x]**x-gts-pattern-ref** - pattern-valued string fields: GTS identifier pattern syntax and coverage by an operand, independent of the registry (spec §9.6.2, §10)
39
+
-[x]**x-gts-final / x-gts-abstract** - GTS Type Schema modifiers controlling inheritance and instantiation
38
40
-[x]**YAML support** - to support YAML files (*.yml, *.yaml) as input files
39
-
-[x]**UUID for instances** - to support UUID as ID in JSON instances
41
+
-[x]**UUID for instances** - to support UUID as ID in JSON instances (anonymous instances)
40
42
-[ ]**TypeSpec support** - direct support for [typespec.io](https://typespec.io/) files (*.tsp) input files
41
43
42
44
Technical Backlog:
@@ -49,7 +51,7 @@ Technical Backlog:
49
51
50
52
## Installation
51
53
52
-
GTS requires Python 3.9 or later.
54
+
GTS requires Python 3.9 or later.`google-re2` ships wheels for CPython 3.10–3.14; on Python 3.9 pip builds it from source, which needs a C++17 compiler and the RE2 and Abseil development headers.
See [gts/README.md](gts/README.md) for full library documentation including schema validation, store operations, query execution, traits, and casting.
96
140
97
-
The web server is a non-production web-server with REST API for the operations processing and testing. It implements reference API for gts-spec [tests](https://github.com/GlobalTypeSystem/gts-spec/tree/main/tests)
141
+
### Web server
98
142
143
+
The web server is a non-production web server with REST API for operations processing and testing. It implements the reference API for [gts-spec tests](https://github.com/GlobalTypeSystem/gts-spec/tree/main/tests).
99
144
100
145
```bash
101
-
#start the web server, default location is http://127.0.0.1:8000
102
-
gts serve
146
+
#Start the web server (default: http://127.0.0.1:8000)
147
+
gts server
103
148
104
-
#start the web server on different port
149
+
#Start the web server on a different port
105
150
gts server --port 8081
106
151
107
-
# pre-populate server with the JSON instancens and schemas from the gts-spec tests
108
-
gts server --path {PATH_TO_JSON_FILES}
152
+
# Pre-populate server with entities from files or directories
153
+
gts --path {PATH_TO_JSON_FILES} server
154
+
155
+
# Allow re-registering an entity with different content (default: reject with 409 Conflict)
-`GET /attr?gts_with_path=<id@path>` - Retrieve attribute value (OP#11)
189
+
-`POST /validate-type-schema` - Validate derived Type Schema against base chain (OP#12)
190
+
-`POST /validate-entity` - Validate entity by GTS ID (OP#12/OP#13)
191
+
192
+
## Development
193
+
194
+
Common development tasks are wrapped in the `Makefile`:
195
+
196
+
```bash
197
+
make py-env # create/update virtualenv and install dependencies
198
+
make install # install gts in editable mode
199
+
make build # build source and wheel distributions into dist/
200
+
make check # run all quality checks (fmt, lint, mypy, test, e2e)
201
+
make test# run unit tests
202
+
make coverage # measure code coverage
203
+
make fmt # check code formatting (ruff)
204
+
make dev-fmt # auto-format code (ruff)
205
+
make lint # run linter (ruff)
206
+
make mypy # run type checker
207
+
make security # check dependencies for vulnerabilities (pip-audit)
208
+
```
209
+
210
+
## Testing
118
211
119
212
You can test the gts-python library by utilizing the shared test suite from the [gts-spec](https://github.com/GlobalTypeSystem/gts-spec) specification and executing the tests against the web server.
Copy file name to clipboardExpand all lines: gts/README.md
+10-6Lines changed: 10 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
3
Python helpers and a reference HTTP service for the [Global Type System (GTS)](https://github.com/globaltypesystem/gts-spec). The package supports GTS identifier parsing, JSON Schema-backed validation, schema compatibility and derivation checks, traits, casting, queries, file loading, a CLI, and a FastAPI application.
4
4
5
-
The package targets GTS specification 0.15.0 and requires Python 3.9 or later. `google-re2` ships wheels for CPython 3.10-3.14; on Python 3.9 pip builds it from source, which needs a C++17 compiler and the RE2 and Abseil development headers.
5
+
The package targets GTS specification 0.17.0 and requires Python 3.9 or later. `google-re2` ships wheels for CPython 3.10-3.14; on Python 3.9 pip builds it from source, which needs a C++17 compiler and the RE2 and Abseil development headers.
6
6
7
7
## Installation
8
8
@@ -166,8 +166,8 @@ TypeSpec (`.tsp`) inputs must be compiled to JSON Schema before loading.
166
166
|`get(entity_id)`| Return `GtsEntity` or `None`. |
167
167
|`items()`| Return an iterator over in-memory `(entity_id, entity)` pairs. |
168
168
|`get_schema_content(type_id)`| Return a schema dictionary or raise `KeyError`. |
169
-
|`validate_schema_basic(type_id)`| Check `$ref` format, `x-gts-ref` declarations, and GTS keyword placement. |
170
-
|`validate_schema(type_id)`| Run full JSON Schema, derivation, final/abstract, x-gts-ref, and trait validation. |
169
+
|`validate_schema_basic(type_id)`| Check `$ref` format, GTS reference declarations, and GTS keyword placement. |
170
+
|`validate_schema(type_id)`| Run full JSON Schema, derivation, final/abstract, reference, and trait validation. |
171
171
|`validate_instance(gts_id)`| Validate a well-known or UUID-addressed instance against its type schema. |
172
172
|`is_minor_compatible(old_schema_id, new_schema_id)`| Return compatibility verdicts for two registered schemas. |
173
173
|`cast(from_id, target_schema_id)`| Cast a registered **instance** to a target schema. |
@@ -215,11 +215,15 @@ The library validates schemas with the dialect named by `$schema`; if absent, it
215
215
216
216
During instance validation, GTS references are resolved with `referencing.Registry`. Draft 2019-09 and Draft 2020-12 `$ref` sibling constraints are preserved, so a sibling such as `minLength` is enforced.
217
217
218
-
### `x-gts-ref`
218
+
### GTS references
219
219
220
-
`x-gts-ref`restricts a string value to a GTS ID or pattern. It accepts an absolute `gts.` pattern or a JSON Pointer beginning with `/` that resolves to one. If a store is present, the referenced entity must be registered.
220
+
GTS 0.17 replaces the former `x-gts-ref`with kind-specific entity references `x-gts-type-ref` and `x-gts-instance-ref`, and 0.16 adds `x-gts-pattern-ref`:
221
221
222
-
`x-gts-ref` can appear in `oneOf`, `anyOf`, and `allOf`. For x-gts-ref-only combinator branches, GTS evaluates the x-gts-ref constraints as the combinator condition. For ordinary or mixed JSON Schema branches, normal JSON Schema structural matching determines which branch’s x-gts-ref constraints are applied.
222
+
-`x-gts-type-ref`: restricts a string value to a GTS Type Identifier.
223
+
-`x-gts-instance-ref`: restricts a string value to a GTS Instance Identifier.
224
+
-`x-gts-pattern-ref`: restricts a string value to a GTS identifier pattern covered by the operand (`M(value) ⊆ M(operand)`), evaluated without consulting the registry.
225
+
226
+
The former kind-blind `x-gts-ref` keyword was removed in GTS 0.16 and is rejected on schema validation like any unknown `x-gts-*` keyword.
0 commit comments