Skip to content

Commit f8a8263

Browse files
committed
docs: update README.md
Signed-off-by: Artifizer <artifizer@gmail.com>
1 parent 6d80768 commit f8a8263

2 files changed

Lines changed: 124 additions & 27 deletions

File tree

‎README.md‎

Lines changed: 114 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22
33
# GTS Python Library
44

5-
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.
66

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.
88

99
## Roadmap
1010

@@ -29,14 +29,16 @@ Featureset:
2929

3030
See details in [gts/README.md](gts/README.md)
3131

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:
3333

3434
- [x] **In-memory entities registry** - simple GTS entities registry with optional GTS references validation on entity registration
3535
- [x] **CLI** - command-line interface for all GTS operations
3636
- [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
37+
- [x] **x-gts-type-ref / x-gts-instance-ref** - kind-specific GTS entity references in schemas (spec §9.6.1)
38+
- [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
3840
- [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)
4042
- [ ] **TypeSpec support** - direct support for [typespec.io](https://typespec.io/) files (*.tsp) input files
4143

4244
Technical Backlog:
@@ -49,7 +51,7 @@ Technical Backlog:
4951

5052
## Installation
5153

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.
5355

5456
### Local development
5557

@@ -82,39 +84,130 @@ pip install gts
8284
### CLI
8385

8486
```bash
85-
gts <command> <args>
86-
87-
# see available commands
87+
# Basic operations
88+
gts validate-id --gts-id 'gts.example.demo._.event.v1~'
89+
gts parse-id --gts-id 'gts.example.demo._.event.v1~'
90+
gts match-id-pattern --candidate 'gts.example.demo._.event.v1~' --pattern 'gts.example.*'
91+
gts uuid --gts-id 'gts.example.demo._.event.v1~'
92+
93+
# Operations with loaded entities
94+
gts --path ./examples validate-instance --gts-id 'gts.example.demo._.event.v1~example.demo._.created.v1'
95+
gts --path ./examples validate-type-schema --gts-id 'gts.example.demo._.event.v1.1~'
96+
gts --path ./examples validate-entity --gts-id 'gts.example.demo._.event.v1~'
97+
gts --path ./examples resolve-relationships --gts-id 'gts.example.demo._.event.v1~'
98+
gts --path ./examples compatibility --old-schema-id 'gts.example.demo._.event.v1.0~' --new-schema-id 'gts.example.demo._.event.v1.1~'
99+
gts --path ./examples cast --from-id 'gts.example.demo._.event.v1~example.demo._.created.v1' --to-schema-id 'gts.example.demo._.event.v1.1~'
100+
gts --path ./examples query --expr 'gts.example.*' --limit 10
101+
gts --path ./examples attr --gts-with-path 'gts.example.demo._.event.v1~@properties.name'
102+
gts --path ./examples list --limit 100
103+
104+
# See all commands and options
88105
gts --help
89106
```
90107

91108
### Library
92109

93-
See [gts/README.md](gts/README.md)
110+
`GtsOps` provides the high-level in-memory API:
94111

95-
### Web server
112+
```python
113+
from gts.ops import GtsOps
114+
115+
ops = GtsOps()
116+
117+
# OP#1 - ID Validation
118+
result = ops.validate_id("gts.example.demo._.event.v1~")
119+
assert result.valid
120+
121+
# OP#2 - ID Extraction
122+
extracted = ops.extract_id({"id": "gts.example.demo._.event.v1.0", "name": "Event"})
123+
print(extracted.id)
124+
125+
# OP#3 - ID Parsing
126+
parsed = ops.parse_id("gts.example.demo._.event.v1~")
127+
for seg in parsed.segments:
128+
print(seg.vendor, seg.package, seg.type, seg.ver_major)
129+
130+
# OP#4 - Pattern Matching
131+
match = ops.match_id_pattern("gts.example.demo._.event.v1.0", "gts.example.*")
132+
assert match.match
133+
134+
# OP#5 - ID to UUID Mapping
135+
uuid_res = ops.uuid("gts.example.demo._.event.v1~")
136+
print(uuid_res.uuid)
137+
```
138+
139+
See [gts/README.md](gts/README.md) for full library documentation including schema validation, store operations, query execution, traits, and casting.
96140

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
98142

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).
99144

100145
```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
103148

104-
# start the web server on different port
149+
# Start the web server on a different port
105150
gts server --port 8081
106151

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)
156+
gts server --allow-entity-updates
109157

110-
# Generate the OpenAPI schema
111-
curl -s http://127.0.0.1:8000/openapi.json | jq > ./gts/openapi.json
158+
# Generate the OpenAPI specification
159+
gts openapi-spec --out openapi.json
112160

113-
# See the schema
161+
# Or fetch from running server
162+
curl -s http://127.0.0.1:8000/openapi.json | jq > ./openapi.json
114163
curl -s http://127.0.0.1:8000/openapi.json | jq | less -S
115164
```
116165

117-
### Testing
166+
#### API Endpoints
167+
168+
##### Entity Management
169+
- `GET /entities` - List registered entities (`limit` query parameter, 1–1000)
170+
- `GET /entities/{gts_id}` - Retrieve a specific entity
171+
- `POST /entities` - Register a single entity (optional `?validate=true`)
172+
- `POST /entities/bulk` - Register multiple entities
173+
- `POST /type-schemas` - Register a batch of GTS Type Schemas (each `type_id` derived from its embedded `$id`)
174+
175+
##### GTS Operations
176+
- `GET /validate-id?gts_id=<id>` - Validate GTS ID (OP#1)
177+
- `POST /extract-id` - Extract GTS ID from JSON (OP#2)
178+
- `GET /parse-id?gts_id=<id>` - Parse GTS ID (OP#3)
179+
- `GET /match-id-pattern?candidate=<id>&pattern=<pat>` - Match pattern (OP#4)
180+
- `GET /uuid?gts_id=<id>` - Generate UUID (OP#5)
181+
- `POST /validate-instance` - Validate registered instance (OP#6)
182+
- `POST /validate-json` - Validate transient instance or Type Schema JSON without registering (OP#6)
183+
- `POST /validate-json/{gts_type}` - Validate transient instance JSON against explicit type (OP#6)
184+
- `GET /resolve-relationships?gts_id=<id>` - Resolve relationships and detect broken references (OP#7)
185+
- `GET /compatibility?old_type_id=<id>&new_type_id=<id>` - Check Type Schema evolution compatibility (OP#8)
186+
- `POST /cast` - Cast instance to target schema (OP#9)
187+
- `GET /query?expr=<expr>&limit=<limit>` - Query entities (OP#10)
188+
- `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
118211

119212
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.
120213

‎gts/README.md‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
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.
44

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.
66

77
## Installation
88

@@ -166,8 +166,8 @@ TypeSpec (`.tsp`) inputs must be compiled to JSON Schema before loading.
166166
| `get(entity_id)` | Return `GtsEntity` or `None`. |
167167
| `items()` | Return an iterator over in-memory `(entity_id, entity)` pairs. |
168168
| `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. |
171171
| `validate_instance(gts_id)` | Validate a well-known or UUID-addressed instance against its type schema. |
172172
| `is_minor_compatible(old_schema_id, new_schema_id)` | Return compatibility verdicts for two registered schemas. |
173173
| `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
215215

216216
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.
217217

218-
### `x-gts-ref`
218+
### GTS references
219219

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`:
221221

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.
223227

224228
### `x-gts-final` and `x-gts-abstract`
225229

0 commit comments

Comments
 (0)