@withgateway/sdk 0.2.6 → 0.2.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +24 -8
- package/dist/cli.js +15468 -11263
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +15233 -11028
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.d.mts +1 -1
- package/dist/files/index.d.ts +1 -1
- package/dist/files/index.js +291 -40
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +284 -37
- package/dist/files/index.mjs.map +1 -1
- package/dist/hooks/index.d.mts +1 -1
- package/dist/hooks/index.d.ts +1 -1
- package/dist/hooks/index.js +203 -47
- package/dist/hooks/index.js.map +1 -1
- package/dist/hooks/index.mjs +198 -42
- package/dist/hooks/index.mjs.map +1 -1
- package/dist/{index-BaKu5ZSU.d.mts → index-C3UzD0G3.d.mts} +75 -1
- package/dist/{index-BaKu5ZSU.d.ts → index-C3UzD0G3.d.ts} +75 -1
- package/dist/{index-CLkMr6VG.d.ts → index-D-_4Ibcn.d.ts} +36 -4
- package/dist/{index-CdbmO4aX.d.mts → index-FfK4Nump.d.mts} +36 -4
- package/dist/index.d.mts +3 -3
- package/dist/index.d.ts +3 -3
- package/dist/index.js +2149 -615
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +2053 -566
- package/dist/index.mjs.map +1 -1
- package/dist/traces/index.js +268 -31
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +262 -28
- package/dist/traces/index.mjs.map +1 -1
- package/dist/tracing/index.js +19 -11
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +19 -11
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +886 -117
- package/dist/worlds/index.d.ts +886 -117
- package/dist/worlds/index.js +1770 -452
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +1752 -434
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +14 -10
- package/runtime/gatewaysdk/environment/_toml.py +3 -10
- package/runtime/gatewaysdk/environment/_world.py +95 -28
- package/runtime/gatewaysdk/environment/runtime.py +10 -6
- package/runtime/gatewaysdk/environment/schema/__main__.py +35 -0
- package/runtime/gatewaysdk/environment/schema/api.py +19 -23
- package/runtime/gatewaysdk/environment/schema/batch.py +68 -14
- package/runtime/gatewaysdk/environment/schema/bundle_runtime.py +4 -2
- package/runtime/gatewaysdk/environment/schema/cast.py +264 -0
- package/runtime/gatewaysdk/environment/schema/compiler.py +35 -1
- package/runtime/gatewaysdk/environment/schema/conform.py +28 -10
- package/runtime/gatewaysdk/environment/schema/connector.py +59 -14
- package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +38 -1
- package/runtime/gatewaysdk/environment/schema/connectors/google-drive/readers/merge.toml +3 -1
- package/runtime/gatewaysdk/environment/schema/credentials.py +20 -0
- package/runtime/gatewaysdk/environment/schema/csv_rows.py +117 -0
- package/runtime/gatewaysdk/environment/schema/cycles.py +121 -0
- package/runtime/gatewaysdk/environment/schema/data.py +21 -5
- package/runtime/gatewaysdk/environment/schema/grading.py +95 -13
- package/runtime/gatewaysdk/environment/schema/handler_errors.py +44 -0
- package/runtime/gatewaysdk/environment/schema/handler_scan.py +175 -0
- package/runtime/gatewaysdk/environment/schema/host.py +68 -115
- package/runtime/gatewaysdk/environment/schema/host_requests.py +78 -0
- package/runtime/gatewaysdk/environment/schema/host_surfaces.py +12 -0
- package/runtime/gatewaysdk/environment/schema/ingest.py +5 -18
- package/runtime/gatewaysdk/environment/schema/local.py +7 -10
- package/runtime/gatewaysdk/environment/schema/openapi_document.py +322 -0
- package/runtime/gatewaysdk/environment/schema/openapi_import.py +382 -0
- package/runtime/gatewaysdk/environment/schema/openapi_routes.py +441 -0
- package/runtime/gatewaysdk/environment/schema/openapi_schemas.py +629 -0
- package/runtime/gatewaysdk/environment/schema/openapi_source.py +210 -0
- package/runtime/gatewaysdk/environment/schema/platform.py +110 -299
- package/runtime/gatewaysdk/environment/schema/platform_import.py +182 -0
- package/runtime/gatewaysdk/environment/schema/platform_query.py +95 -0
- package/runtime/gatewaysdk/environment/schema/route_bindings.py +176 -0
- package/runtime/gatewaysdk/environment/schema/runtime.py +56 -7
- package/runtime/gatewaysdk/environment/schema/scaffold.py +64 -5
- package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +70 -22
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +54 -4
- package/runtime/gatewaysdk/environment/schema/skills/hooks-getting-started/SKILL.md +27 -2
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +62 -0
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +91 -54
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +146 -146
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +11 -7
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +30 -0
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/new-world-sandbox.md +43 -0
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/openapi-import.md +90 -0
- package/runtime/gatewaysdk/environment/schema/store.py +15 -6
- package/runtime/gatewaysdk/environment/schema/store_contract.py +119 -0
- package/runtime/gatewaysdk/environment/schema/tasks.py +121 -32
- package/runtime/gatewaysdk/environment/schema/tools_world.py +32 -10
- package/runtime/gatewaysdk/environment/schema/tree_import.py +228 -0
- package/runtime/gatewaysdk/environment/schema/ui.py +18 -2
- package/runtime/gatewaysdk/environment/schema/validation.py +35 -0
- package/runtime/gatewaysdk/environment/schema/verbs.py +8 -2
- package/runtime/gatewaysdk/environment/world.py +42 -3
- package/runtime/gatewaysdk/environment/world_session_contract.py +57 -0
- package/skills/benchmarks-getting-started/SKILL.md +70 -22
- package/skills/connector-schema-authoring/SKILL.md +54 -4
- package/skills/connector-schema-authoring/connector-worlds.md +21 -7
- package/skills/connector-schema-authoring/world-schema.md +144 -83
- package/skills/hooks-getting-started/SKILL.md +27 -2
- package/skills/world-data-ingestion/ROWS.md +62 -0
- package/skills/world-data-ingestion/SKILL.md +91 -54
- package/skills/worlds-getting-started/SKILL.md +146 -146
- package/skills/worlds-getting-started/references/cli-mcp-map.md +11 -7
- package/skills/worlds-getting-started/references/gotchas.md +30 -0
- package/skills/worlds-getting-started/references/new-world-sandbox.md +43 -0
- package/skills/worlds-getting-started/references/openapi-import.md +90 -0
|
@@ -0,0 +1,629 @@
|
|
|
1
|
+
"""OpenAPI schemas to world.json ``$defs``: names, keys and the JSON Schema dialect.
|
|
2
|
+
|
|
3
|
+
Three concerns live here, each a class:
|
|
4
|
+
|
|
5
|
+
- :class:`Names` turns the vendor's spelling (``findPetsByStatus``,
|
|
6
|
+
``nullable-simple-user``) into the identifiers the compiler accepts
|
|
7
|
+
(snake_case entity and operation names, plural entity names, legal field
|
|
8
|
+
names) and :class:`Namespace` keeps them unique with a numeric suffix.
|
|
9
|
+
- :class:`EntityKey` picks a schema's primary key: ``id``, then ``<name>Id`` /
|
|
10
|
+
``<name>_id``, then a ``readOnly`` field the vendor marks unique in an ``x-``
|
|
11
|
+
extension, then the first required string or integer.
|
|
12
|
+
- :class:`SchemaConverter` rewrites the vendor's schemas into the subset
|
|
13
|
+
``validation.py`` accepts: ``allOf`` merged, ``nullable`` folded into the
|
|
14
|
+
type, ``$ref`` re-pointed at ``#/$defs``, keywords the validator does not know
|
|
15
|
+
dropped and counted. Every top-level schema converts once, iteratively over a
|
|
16
|
+
worklist, so a document with a thousand schemas costs one pass over them; a
|
|
17
|
+
schema whose root reaches itself through ``$ref``/``allOf`` before it reaches
|
|
18
|
+
a property is refused with its pointer, because such a root has no shape.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
from __future__ import annotations
|
|
22
|
+
|
|
23
|
+
import re
|
|
24
|
+
from collections import Counter, deque
|
|
25
|
+
from dataclasses import dataclass, field
|
|
26
|
+
from typing import Any
|
|
27
|
+
|
|
28
|
+
from .compiler import FIELD_RESERVED, RESERVED, RESERVED_STATE_KEYS
|
|
29
|
+
from .openapi_document import OpenApiDocument
|
|
30
|
+
from .validation import fail, pointer
|
|
31
|
+
|
|
32
|
+
IDENTIFIER = re.compile(r"^[A-Za-z][A-Za-z0-9_]*$")
|
|
33
|
+
FIELD_IDENTIFIER = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
|
|
34
|
+
RESERVED_FIELDS = frozenset({"_key", "payload"})
|
|
35
|
+
#: A ``$def`` for a value the vendor leaves untyped (``{}``, ``additionalProperties: true``
|
|
36
|
+
#: at the top). Not recursive on purpose: the validator wants recursive targets typed.
|
|
37
|
+
ANY_JSON = {
|
|
38
|
+
"anyOf": [
|
|
39
|
+
{"type": "string"},
|
|
40
|
+
{"type": "number"},
|
|
41
|
+
{"type": "boolean"},
|
|
42
|
+
{"type": "null"},
|
|
43
|
+
{"type": "object", "additionalProperties": True},
|
|
44
|
+
{
|
|
45
|
+
"type": "array",
|
|
46
|
+
"items": {
|
|
47
|
+
"anyOf": [
|
|
48
|
+
{"type": "string"},
|
|
49
|
+
{"type": "number"},
|
|
50
|
+
{"type": "boolean"},
|
|
51
|
+
{"type": "null"},
|
|
52
|
+
{"type": "object", "additionalProperties": True},
|
|
53
|
+
]
|
|
54
|
+
},
|
|
55
|
+
},
|
|
56
|
+
]
|
|
57
|
+
}
|
|
58
|
+
_STRING_FORMATS = frozenset({"date", "time", "date-time"})
|
|
59
|
+
_DOC_KEYS = ("title", "description")
|
|
60
|
+
_FLAG_KEYS = ("deprecated", "readOnly", "writeOnly")
|
|
61
|
+
_SCALARS = frozenset({"string", "integer", "number", "boolean", "null"})
|
|
62
|
+
_TYPES = _SCALARS | {"object", "array"}
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
class Names:
|
|
66
|
+
"""The vendor's spelling, made legal for the compiler."""
|
|
67
|
+
|
|
68
|
+
@staticmethod
|
|
69
|
+
def snake(text: str) -> str:
|
|
70
|
+
text = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", text)
|
|
71
|
+
text = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1_\2", text)
|
|
72
|
+
text = re.sub(r"[^A-Za-z0-9]+", "_", text).strip("_").lower()
|
|
73
|
+
return re.sub(r"_+", "_", text)
|
|
74
|
+
|
|
75
|
+
@staticmethod
|
|
76
|
+
def plural(word: str) -> str:
|
|
77
|
+
if word.endswith(("ss", "x", "z", "ch", "sh")):
|
|
78
|
+
return word + "es"
|
|
79
|
+
if word.endswith("s"):
|
|
80
|
+
return word
|
|
81
|
+
if re.search(r"[^aeiou]y$", word):
|
|
82
|
+
return word[:-1] + "ies"
|
|
83
|
+
return word + "s"
|
|
84
|
+
|
|
85
|
+
@classmethod
|
|
86
|
+
def entity(cls, source: str, limit: int) -> str:
|
|
87
|
+
"""``Pet`` → ``pets``, ``nullable-simple-user`` → ``nullable_simple_users``; at most ``limit`` long."""
|
|
88
|
+
name = cls.plural(cls.snake(source)) or "entity"
|
|
89
|
+
if not name[0].isalpha():
|
|
90
|
+
name = "e_" + name
|
|
91
|
+
if name.startswith(RESERVED) or name in RESERVED_STATE_KEYS:
|
|
92
|
+
name = "x_" + name
|
|
93
|
+
return name[:limit].rstrip("_") or "entity"
|
|
94
|
+
|
|
95
|
+
@classmethod
|
|
96
|
+
def operation(cls, source: str, limit: int) -> str:
|
|
97
|
+
"""An ``operationId`` as a bounded snake_case operation name."""
|
|
98
|
+
name = cls.snake(source) or "operation"
|
|
99
|
+
if not name[0].isalpha():
|
|
100
|
+
name = "op_" + name
|
|
101
|
+
return name[:limit].rstrip("_") or "operation"
|
|
102
|
+
|
|
103
|
+
@staticmethod
|
|
104
|
+
def field(source: str) -> str:
|
|
105
|
+
"""A property name the compiler accepts; the source name when it already is one."""
|
|
106
|
+
name = re.sub(r"[^A-Za-z0-9_]", "_", source)
|
|
107
|
+
if not name or not FIELD_IDENTIFIER.match(name):
|
|
108
|
+
name = "f_" + name
|
|
109
|
+
if name in RESERVED_FIELDS or name.startswith(FIELD_RESERVED):
|
|
110
|
+
name = "f_" + name
|
|
111
|
+
return name
|
|
112
|
+
|
|
113
|
+
@classmethod
|
|
114
|
+
def fields(cls, properties: dict[str, Any]) -> dict[str, str]:
|
|
115
|
+
"""Source property -> the field name it is stored under, collisions suffixed."""
|
|
116
|
+
names = Namespace()
|
|
117
|
+
return {source: names.claim(cls.field(source))[0] for source in properties}
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
@dataclass
|
|
121
|
+
class Namespace:
|
|
122
|
+
"""Names claimed so far (case-insensitively); a taken name gets ``_2``, ``_3``…"""
|
|
123
|
+
|
|
124
|
+
limit: int | None = None
|
|
125
|
+
taken: set[str] = field(default_factory=set)
|
|
126
|
+
#: Where the probe for a base resumes, so n claims of one name cost n, not n².
|
|
127
|
+
next_suffix: dict[str, int] = field(default_factory=dict)
|
|
128
|
+
|
|
129
|
+
def claim(self, base: str) -> tuple[str, bool]:
|
|
130
|
+
"""(the name granted, whether it had to be suffixed)."""
|
|
131
|
+
if base.lower() not in self.taken:
|
|
132
|
+
self.taken.add(base.lower())
|
|
133
|
+
return base, False
|
|
134
|
+
suffix = self.next_suffix.get(base.lower(), 2)
|
|
135
|
+
while True:
|
|
136
|
+
stem = base if self.limit is None else base[: self.limit - len(str(suffix)) - 1].rstrip("_")
|
|
137
|
+
candidate = f"{stem}_{suffix}"
|
|
138
|
+
suffix += 1
|
|
139
|
+
if candidate.lower() not in self.taken:
|
|
140
|
+
self.taken.add(candidate.lower())
|
|
141
|
+
self.next_suffix[base.lower()] = suffix
|
|
142
|
+
return candidate, True
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
SCALARS = frozenset({"string", "integer", "number", "boolean"})
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
class EntityKey:
|
|
149
|
+
"""Which property is a schema's primary key, and whether it is fit to be one."""
|
|
150
|
+
|
|
151
|
+
UNIQUE_EXTENSIONS = ("x-unique", "x-primary-key", "x-primaryKey", "x-identifier")
|
|
152
|
+
|
|
153
|
+
def __init__(self, document: OpenApiDocument, source: str, properties: dict[str, Any], required: set[str]):
|
|
154
|
+
self.document = document
|
|
155
|
+
self.source = source
|
|
156
|
+
self.properties = properties
|
|
157
|
+
self.required = required
|
|
158
|
+
|
|
159
|
+
def detect(self, *, fallback: bool = True) -> str | None:
|
|
160
|
+
"""``id``, ``<name>Id``/``<name>_id``, a ``readOnly`` property marked unique by an
|
|
161
|
+
``x-`` extension, else (when ``fallback``) the first required scalar."""
|
|
162
|
+
for name in self._id_like():
|
|
163
|
+
if self._keyable(name):
|
|
164
|
+
return name
|
|
165
|
+
for name, schema in self.properties.items():
|
|
166
|
+
resolved = self._resolved(schema)
|
|
167
|
+
if (
|
|
168
|
+
resolved.get("readOnly") is True
|
|
169
|
+
and any(resolved.get(x) is True for x in self.UNIQUE_EXTENSIONS)
|
|
170
|
+
and self._keyable(name)
|
|
171
|
+
):
|
|
172
|
+
return name
|
|
173
|
+
if not fallback:
|
|
174
|
+
return None
|
|
175
|
+
for name in self.properties:
|
|
176
|
+
if name in self.required and self._keyable(name):
|
|
177
|
+
return name
|
|
178
|
+
return None
|
|
179
|
+
|
|
180
|
+
def scalars(self) -> frozenset[str]:
|
|
181
|
+
"""Properties a filter can compare: string, integer, number or boolean."""
|
|
182
|
+
return frozenset(name for name in self.properties if self._scalar_type(name) in SCALARS)
|
|
183
|
+
|
|
184
|
+
def _scalar_type(self, name: str) -> str | None:
|
|
185
|
+
resolved = self._resolved(self.properties[name])
|
|
186
|
+
types = resolved.get("type")
|
|
187
|
+
if isinstance(types, list):
|
|
188
|
+
types = [t for t in types if t != "null"]
|
|
189
|
+
types = types[0] if len(types) == 1 else None
|
|
190
|
+
return types if isinstance(types, str) and not resolved.get("properties") else None
|
|
191
|
+
|
|
192
|
+
def _id_like(self) -> list[str]:
|
|
193
|
+
singular = Names.snake(self.source)
|
|
194
|
+
camel = re.sub(r"_([a-z0-9])", lambda m: m.group(1).upper(), singular)
|
|
195
|
+
candidates = ["id", "ID", "Id", f"{camel}Id", f"{camel}_id", f"{singular}_id", f"{singular}Id", f"{camel}ID"]
|
|
196
|
+
return [c for c in dict.fromkeys(candidates) if c in self.properties]
|
|
197
|
+
|
|
198
|
+
def _keyable(self, name: str) -> bool:
|
|
199
|
+
"""A key is a string or integer that is never null."""
|
|
200
|
+
resolved = self._resolved(self.properties[name])
|
|
201
|
+
types = resolved.get("type")
|
|
202
|
+
nullable = resolved.get("nullable") is True or (isinstance(types, list) and "null" in types)
|
|
203
|
+
return not nullable and self._scalar_type(name) in ("string", "integer")
|
|
204
|
+
|
|
205
|
+
def _resolved(self, schema: Any) -> dict:
|
|
206
|
+
resolved = self.document.resolve(schema, f"{self.document.schemas_pointer}/{pointer(self.source)}/properties")
|
|
207
|
+
return resolved if isinstance(resolved, dict) else {}
|
|
208
|
+
|
|
209
|
+
|
|
210
|
+
@dataclass
|
|
211
|
+
class ConvertedDef:
|
|
212
|
+
name: str
|
|
213
|
+
schema: dict
|
|
214
|
+
fields: dict[str, str] # entity roots: source property → field name
|
|
215
|
+
|
|
216
|
+
|
|
217
|
+
class SchemaConverter:
|
|
218
|
+
"""The document's schemas as world.json ``$defs``, converted once each."""
|
|
219
|
+
|
|
220
|
+
def __init__(self, document: OpenApiDocument, roots: dict[str, str]):
|
|
221
|
+
"""``roots`` maps the source names that become entities to their key property."""
|
|
222
|
+
self.document = document
|
|
223
|
+
self.roots = roots
|
|
224
|
+
self.defs: dict[str, dict] = {}
|
|
225
|
+
self.fields: dict[str, dict[str, str]] = {}
|
|
226
|
+
self.dropped: Counter[str] = Counter()
|
|
227
|
+
self.renamed: list[tuple[str, str, str]] = []
|
|
228
|
+
self.warnings: list[str] = []
|
|
229
|
+
self._queue: deque[str] = deque()
|
|
230
|
+
self._any_json: str | None = None
|
|
231
|
+
self._merged: dict[str, dict] = {}
|
|
232
|
+
self._alias_of: dict[str, str] = {}
|
|
233
|
+
#: name → (the node its ``$ref`` chain ends at, the names walked from it inclusive).
|
|
234
|
+
self._tails: dict[str, tuple[Any, tuple[str, ...]]] = {}
|
|
235
|
+
self._names = Namespace()
|
|
236
|
+
for name in self.document.schemas:
|
|
237
|
+
self._names.claim(name)
|
|
238
|
+
|
|
239
|
+
# ------------------------------------------------------------- public
|
|
240
|
+
|
|
241
|
+
def convert_all(self, wanted: set[str]) -> dict[str, dict]:
|
|
242
|
+
"""Convert ``wanted`` and everything they reference, in order of discovery."""
|
|
243
|
+
for name in sorted(wanted):
|
|
244
|
+
self._want(name)
|
|
245
|
+
while self._queue:
|
|
246
|
+
name = self._queue.popleft()
|
|
247
|
+
if name in self.defs:
|
|
248
|
+
continue
|
|
249
|
+
self.defs[name] = self._convert_def(name)
|
|
250
|
+
return dict(sorted(self.defs.items()))
|
|
251
|
+
|
|
252
|
+
def reference(self, name: str) -> str:
|
|
253
|
+
"""The ``$ref`` a world.json node uses for a top-level schema."""
|
|
254
|
+
self._want(name)
|
|
255
|
+
return f"#/$defs/{pointer(name)}"
|
|
256
|
+
|
|
257
|
+
def any_json(self) -> dict:
|
|
258
|
+
if self._any_json is None:
|
|
259
|
+
self._any_json, _ = self._names.claim("AnyJson")
|
|
260
|
+
self.defs[self._any_json] = ANY_JSON
|
|
261
|
+
return {"$ref": f"#/$defs/{pointer(self._any_json)}"}
|
|
262
|
+
|
|
263
|
+
def _want(self, name: str) -> None:
|
|
264
|
+
if name not in self.defs and name not in self._queue:
|
|
265
|
+
self._queue.append(name)
|
|
266
|
+
|
|
267
|
+
# ------------------------------------------------------------- one top-level schema
|
|
268
|
+
|
|
269
|
+
def _convert_def(self, name: str) -> dict:
|
|
270
|
+
at = f"{self.document.schemas_pointer}/{pointer(name)}"
|
|
271
|
+
raw = self.document.schemas[name]
|
|
272
|
+
if not isinstance(raw, dict):
|
|
273
|
+
fail("spec", f"Schema {name} must be an object", at)
|
|
274
|
+
key = self.roots.get(name)
|
|
275
|
+
if key is None and isinstance(raw.get("$ref"), str):
|
|
276
|
+
return self._alias(name, raw, at)
|
|
277
|
+
resolved, chain = self.resolve_named(raw, at, (name,))
|
|
278
|
+
if not isinstance(resolved, dict):
|
|
279
|
+
fail("spec", f"Schema {name} must be an object", at)
|
|
280
|
+
merged = self.merged(resolved, at, chain)
|
|
281
|
+
if key is None:
|
|
282
|
+
return self.convert(merged, at, chain, resolve_root=False)
|
|
283
|
+
return self._entity_root(name, merged, at, key)
|
|
284
|
+
|
|
285
|
+
def _entity_root(self, name: str, merged: dict, at: str, key: str) -> dict:
|
|
286
|
+
converted = self.convert(merged, at, (name,), resolve_root=False)
|
|
287
|
+
properties = converted.get("properties")
|
|
288
|
+
if "object" not in _type_list(converted.get("type")) or not isinstance(properties, dict):
|
|
289
|
+
fail("spec", f"Schema {name} is not an object schema, so it cannot be an entity", at)
|
|
290
|
+
converted["type"] = "object"
|
|
291
|
+
converted.setdefault("title", name)
|
|
292
|
+
converted["$comment"] = f"source: {at}"
|
|
293
|
+
renamed = Names.fields(properties)
|
|
294
|
+
self.renamed.extend((f"{at}/properties/{pointer(src)}", src, dst) for src, dst in renamed.items() if src != dst)
|
|
295
|
+
converted["properties"] = {renamed[k]: v for k, v in properties.items()}
|
|
296
|
+
required = [renamed[r] for r in converted.get("required", []) if r in renamed]
|
|
297
|
+
if renamed[key] not in required:
|
|
298
|
+
required.append(renamed[key])
|
|
299
|
+
converted["required"] = required
|
|
300
|
+
converted["additionalProperties"] = False
|
|
301
|
+
converted.pop("anyOf", None)
|
|
302
|
+
converted.pop("oneOf", None)
|
|
303
|
+
self.fields[name] = renamed
|
|
304
|
+
return converted
|
|
305
|
+
|
|
306
|
+
def _alias(self, name: str, raw: dict, at: str) -> dict:
|
|
307
|
+
"""A ``$ref``-only schema: a def that points straight at the end of its
|
|
308
|
+
chain, so a thousand chained aliases cost one walk, not a thousand."""
|
|
309
|
+
target = self._alias_of.get(name)
|
|
310
|
+
if target is None:
|
|
311
|
+
_, chain = self.resolve_named(raw, at, (name,))
|
|
312
|
+
target = chain[-1]
|
|
313
|
+
for alias in chain[:-1]:
|
|
314
|
+
self._alias_of.setdefault(alias, target)
|
|
315
|
+
if target == name:
|
|
316
|
+
return self.convert(self.document.lookup(raw["$ref"], at), at, (name,))
|
|
317
|
+
out: dict = {"$ref": self.reference(target)}
|
|
318
|
+
for key in _DOC_KEYS:
|
|
319
|
+
if isinstance(raw.get(key), str):
|
|
320
|
+
out[key] = raw[key]
|
|
321
|
+
return {"anyOf": [out, {"type": "null"}]} if _nullable(raw) else out
|
|
322
|
+
|
|
323
|
+
# ------------------------------------------------------------- allOf
|
|
324
|
+
|
|
325
|
+
def merged(self, resolved: dict, at: str, chain: tuple[str, ...]) -> dict:
|
|
326
|
+
""":meth:`merge` of a named schema, computed once: a diamond of ``allOf``
|
|
327
|
+
members (``A → B, C → D``) costs one merge of ``D``, not one per path."""
|
|
328
|
+
name = chain[-1]
|
|
329
|
+
if name not in self._merged:
|
|
330
|
+
self._merged[name] = self.merge(resolved, at, chain)
|
|
331
|
+
return self._merged[name]
|
|
332
|
+
|
|
333
|
+
def merge(self, raw: dict, at: str, stack: tuple[str, ...]) -> dict:
|
|
334
|
+
"""``allOf`` of object members folded into one object schema; other
|
|
335
|
+
compositions are left for :meth:`convert`."""
|
|
336
|
+
members = raw.get("allOf")
|
|
337
|
+
if not isinstance(members, list) or not members:
|
|
338
|
+
return raw
|
|
339
|
+
flat: list[dict] = []
|
|
340
|
+
for index, member in enumerate(members):
|
|
341
|
+
here = f"{at}/allOf/{index}"
|
|
342
|
+
resolved, chain = self.resolve_named(member, here, stack)
|
|
343
|
+
if not isinstance(resolved, dict):
|
|
344
|
+
fail("spec", "allOf members must be schemas", here)
|
|
345
|
+
flat.append(
|
|
346
|
+
self.merged(resolved, here, chain) if len(chain) > len(stack) else self.merge(resolved, here, chain)
|
|
347
|
+
)
|
|
348
|
+
if not all(_object_like(m) for m in flat):
|
|
349
|
+
return raw
|
|
350
|
+
merged: dict = {k: v for k, v in raw.items() if k != "allOf"}
|
|
351
|
+
properties: dict = {}
|
|
352
|
+
required: list[str] = []
|
|
353
|
+
closed = False
|
|
354
|
+
for member in flat:
|
|
355
|
+
properties.update(member.get("properties") or {})
|
|
356
|
+
required.extend(r for r in member.get("required", []) if isinstance(r, str))
|
|
357
|
+
closed = closed or member.get("additionalProperties") is False
|
|
358
|
+
for doc in (k for k in _DOC_KEYS if isinstance(member.get(k), str)):
|
|
359
|
+
merged.setdefault(doc, member[doc])
|
|
360
|
+
properties.update(merged.get("properties") or {})
|
|
361
|
+
required.extend(r for r in merged.get("required", []) if isinstance(r, str))
|
|
362
|
+
merged.update({"type": "object", "properties": properties, "required": list(dict.fromkeys(required))})
|
|
363
|
+
if closed and "additionalProperties" not in merged:
|
|
364
|
+
merged["additionalProperties"] = False
|
|
365
|
+
return merged
|
|
366
|
+
|
|
367
|
+
def resolve_named(self, node: Any, at: str, stack: tuple[str, ...]) -> tuple[Any, tuple[str, ...]]:
|
|
368
|
+
"""Resolve a node whose ``$ref`` chain must not come back to a schema on
|
|
369
|
+
``stack``: that would make a root out of itself."""
|
|
370
|
+
chain = stack
|
|
371
|
+
fresh: list[str] = [] # names walked for the first time; a known tail ends the walk
|
|
372
|
+
tail: tuple[str, ...] = ()
|
|
373
|
+
while isinstance(node, dict) and isinstance(node.get("$ref"), str):
|
|
374
|
+
name = self.document.schema_name(node["$ref"])
|
|
375
|
+
known = self._tails.get(name) if name is not None else None
|
|
376
|
+
if known is not None:
|
|
377
|
+
node, tail = known
|
|
378
|
+
self._refuse_cycle(chain, tail, at)
|
|
379
|
+
chain = (*chain, *tail)
|
|
380
|
+
break
|
|
381
|
+
if name is not None:
|
|
382
|
+
self._refuse_cycle(chain, (name,), at)
|
|
383
|
+
chain, fresh = (*chain, name), [*fresh, name]
|
|
384
|
+
node = self.document.lookup(node["$ref"], at)
|
|
385
|
+
walked = (*fresh, *tail)
|
|
386
|
+
for index in range(len(fresh)):
|
|
387
|
+
self._tails[fresh[index]] = (node, walked[index:])
|
|
388
|
+
return node, chain
|
|
389
|
+
|
|
390
|
+
@staticmethod
|
|
391
|
+
def _refuse_cycle(chain: tuple[str, ...], tail: tuple[str, ...], at: str) -> None:
|
|
392
|
+
back = next((name for name in tail if name in chain), None)
|
|
393
|
+
if back is None:
|
|
394
|
+
return
|
|
395
|
+
fail(
|
|
396
|
+
"cycle",
|
|
397
|
+
f"Schema {chain[0]} reaches itself through {' -> '.join([*chain, back])} before any property: "
|
|
398
|
+
"an entity root cannot contain itself; reference it from a field instead",
|
|
399
|
+
at,
|
|
400
|
+
)
|
|
401
|
+
|
|
402
|
+
# ------------------------------------------------------------- one schema node
|
|
403
|
+
|
|
404
|
+
def convert(self, raw: Any, at: str, stack: tuple[str, ...], *, resolve_root: bool = True) -> dict:
|
|
405
|
+
if raw is True or raw == {}:
|
|
406
|
+
return self.any_json()
|
|
407
|
+
if not isinstance(raw, dict):
|
|
408
|
+
fail("spec", "A schema must be an object", at)
|
|
409
|
+
if resolve_root and isinstance(raw.get("$ref"), str):
|
|
410
|
+
return self._reference(raw, at, stack)
|
|
411
|
+
raw = self.merge(raw, at, stack)
|
|
412
|
+
if "allOf" in raw:
|
|
413
|
+
return self._composition(raw, "allOf", at, stack)
|
|
414
|
+
types, nullable = self._types(raw, at)
|
|
415
|
+
out: dict = {}
|
|
416
|
+
for key in _DOC_KEYS:
|
|
417
|
+
if isinstance(raw.get(key), str):
|
|
418
|
+
out[key] = raw[key]
|
|
419
|
+
for key in _FLAG_KEYS:
|
|
420
|
+
if raw.get(key) is True:
|
|
421
|
+
out[key] = True
|
|
422
|
+
if not types:
|
|
423
|
+
return self._untyped(raw, out, nullable, at, stack)
|
|
424
|
+
if len(types) > 1:
|
|
425
|
+
variants = [
|
|
426
|
+
self.convert({**raw, "type": t, "nullable": False, "x-nullable": False}, at, stack, resolve_root=False)
|
|
427
|
+
for t in types
|
|
428
|
+
]
|
|
429
|
+
out["anyOf"] = variants + ([{"type": "null"}] if nullable else [])
|
|
430
|
+
return out
|
|
431
|
+
kind = types[0]
|
|
432
|
+
out["type"] = [kind, "null"] if nullable and kind != "null" else kind
|
|
433
|
+
getattr(self, f"_convert_{kind}")(raw, out, at, stack)
|
|
434
|
+
for composition in ("oneOf", "anyOf"):
|
|
435
|
+
if composition in raw:
|
|
436
|
+
out[composition] = self._members(raw[composition], f"{at}/{composition}", stack)
|
|
437
|
+
self._count_dropped(raw, out)
|
|
438
|
+
return out
|
|
439
|
+
|
|
440
|
+
def _reference(self, raw: dict, at: str, stack: tuple[str, ...]) -> dict:
|
|
441
|
+
ref = raw["$ref"]
|
|
442
|
+
name = self.document.schema_name(ref)
|
|
443
|
+
nullable = _nullable(raw)
|
|
444
|
+
if name is None:
|
|
445
|
+
return self.convert(self.document.lookup(ref, at), at, stack)
|
|
446
|
+
if name not in self.document.schemas:
|
|
447
|
+
fail("reference", f"Unknown $ref {ref}", at)
|
|
448
|
+
out: dict = {"$ref": self.reference(name)}
|
|
449
|
+
for key in _DOC_KEYS:
|
|
450
|
+
if isinstance(raw.get(key), str):
|
|
451
|
+
out[key] = raw[key]
|
|
452
|
+
return {"anyOf": [out, {"type": "null"}]} if nullable else out
|
|
453
|
+
|
|
454
|
+
def _composition(self, raw: dict, keyword: str, at: str, stack: tuple[str, ...]) -> dict:
|
|
455
|
+
out: dict = {k: raw[k] for k in _DOC_KEYS if isinstance(raw.get(k), str)}
|
|
456
|
+
out["allOf" if keyword == "allOf" else keyword] = self._members(raw[keyword], f"{at}/{keyword}", stack)
|
|
457
|
+
return out
|
|
458
|
+
|
|
459
|
+
def _members(self, members: Any, at: str, stack: tuple[str, ...]) -> list[dict]:
|
|
460
|
+
if not isinstance(members, list) or not members:
|
|
461
|
+
fail("spec", "A composition needs a non-empty array of schemas", at)
|
|
462
|
+
return [self.convert(m, f"{at}/{i}", stack) for i, m in enumerate(members)]
|
|
463
|
+
|
|
464
|
+
def _types(self, raw: dict, at: str) -> tuple[list[str], bool]:
|
|
465
|
+
declared = raw.get("type")
|
|
466
|
+
types = ["string" if t == "file" else t for t in _type_list(declared)]
|
|
467
|
+
unknown = [t for t in types if t not in _TYPES]
|
|
468
|
+
if unknown:
|
|
469
|
+
fail("spec", f"Unknown type {unknown[0]!r}", f"{at}/type")
|
|
470
|
+
nullable = "null" in types or raw.get("nullable") is True or raw.get("x-nullable") is True
|
|
471
|
+
types = [t for t in dict.fromkeys(types) if t != "null"]
|
|
472
|
+
if not types and declared is not None and "null" in (declared if isinstance(declared, list) else [declared]):
|
|
473
|
+
return ["null"], False
|
|
474
|
+
if not types:
|
|
475
|
+
types = self._infer(raw)
|
|
476
|
+
if isinstance(raw.get("enum"), list) and None in raw["enum"]:
|
|
477
|
+
nullable = True
|
|
478
|
+
return types, nullable
|
|
479
|
+
|
|
480
|
+
@staticmethod
|
|
481
|
+
def _infer(raw: dict) -> list[str]:
|
|
482
|
+
if (
|
|
483
|
+
isinstance(raw.get("properties"), dict)
|
|
484
|
+
or isinstance(raw.get("additionalProperties"), dict)
|
|
485
|
+
or raw.get("additionalProperties") is False
|
|
486
|
+
):
|
|
487
|
+
return ["object"]
|
|
488
|
+
if "items" in raw:
|
|
489
|
+
return ["array"]
|
|
490
|
+
enum = raw.get("enum")
|
|
491
|
+
if isinstance(enum, list) and enum:
|
|
492
|
+
kinds = {_json_type(v) for v in enum if v is not None}
|
|
493
|
+
return sorted(kinds) if kinds and kinds <= _SCALARS else []
|
|
494
|
+
return []
|
|
495
|
+
|
|
496
|
+
def _untyped(self, raw: dict, out: dict, nullable: bool, at: str, stack: tuple[str, ...]) -> dict:
|
|
497
|
+
for composition in ("oneOf", "anyOf"):
|
|
498
|
+
if composition in raw:
|
|
499
|
+
members = self._members(raw[composition], f"{at}/{composition}", stack)
|
|
500
|
+
out[composition] = members + ([{"type": "null"}] if nullable else [])
|
|
501
|
+
return out
|
|
502
|
+
return self.any_json()
|
|
503
|
+
|
|
504
|
+
# ------------------------------------------------------------- per type
|
|
505
|
+
|
|
506
|
+
def _convert_object(self, raw: dict, out: dict, at: str, stack: tuple[str, ...]) -> None:
|
|
507
|
+
self._object_properties(raw, out, at, stack)
|
|
508
|
+
extra = raw.get("additionalProperties")
|
|
509
|
+
if extra is False or extra is True:
|
|
510
|
+
out["additionalProperties"] = extra
|
|
511
|
+
elif isinstance(extra, dict):
|
|
512
|
+
out["additionalProperties"] = (
|
|
513
|
+
True if extra == {} else self.convert(extra, f"{at}/additionalProperties", stack)
|
|
514
|
+
)
|
|
515
|
+
elif "properties" not in out:
|
|
516
|
+
out["additionalProperties"] = True
|
|
517
|
+
|
|
518
|
+
def _object_properties(self, raw: dict, out: dict, at: str, stack: tuple[str, ...]) -> None:
|
|
519
|
+
properties = raw.get("properties")
|
|
520
|
+
if properties is None:
|
|
521
|
+
return
|
|
522
|
+
if not isinstance(properties, dict):
|
|
523
|
+
fail("spec", "properties must be an object", f"{at}/properties")
|
|
524
|
+
out["properties"] = {
|
|
525
|
+
str(name): self.convert(schema, f"{at}/properties/{pointer(name)}", stack)
|
|
526
|
+
for name, schema in properties.items()
|
|
527
|
+
}
|
|
528
|
+
declared = raw.get("required") if isinstance(raw.get("required"), list) else []
|
|
529
|
+
required = [r for r in declared if isinstance(r, str) and r in properties]
|
|
530
|
+
if required:
|
|
531
|
+
out["required"] = list(dict.fromkeys(required))
|
|
532
|
+
|
|
533
|
+
def _convert_array(self, raw: dict, out: dict, at: str, stack: tuple[str, ...]) -> None:
|
|
534
|
+
items = raw.get("items")
|
|
535
|
+
out["items"] = self.convert(items, f"{at}/items", stack) if isinstance(items, dict) else self.any_json()
|
|
536
|
+
for key in ("minItems", "maxItems"):
|
|
537
|
+
if isinstance(raw.get(key), int) and not isinstance(raw[key], bool):
|
|
538
|
+
out[key] = raw[key]
|
|
539
|
+
if raw.get("uniqueItems") is True:
|
|
540
|
+
out["uniqueItems"] = True
|
|
541
|
+
|
|
542
|
+
def _convert_string(self, raw: dict, out: dict, at: str, stack: tuple[str, ...]) -> None:
|
|
543
|
+
if raw.get("format") in _STRING_FORMATS:
|
|
544
|
+
out["format"] = raw["format"]
|
|
545
|
+
for key in ("minLength", "maxLength"):
|
|
546
|
+
if isinstance(raw.get(key), int) and not isinstance(raw[key], bool):
|
|
547
|
+
out[key] = raw[key]
|
|
548
|
+
self._enum(raw, out, "string")
|
|
549
|
+
|
|
550
|
+
def _convert_integer(self, raw: dict, out: dict, at: str, stack: tuple[str, ...]) -> None:
|
|
551
|
+
self._numeric(raw, out)
|
|
552
|
+
self._enum(raw, out, "integer")
|
|
553
|
+
|
|
554
|
+
def _convert_number(self, raw: dict, out: dict, at: str, stack: tuple[str, ...]) -> None:
|
|
555
|
+
self._numeric(raw, out)
|
|
556
|
+
self._enum(raw, out, "number")
|
|
557
|
+
|
|
558
|
+
def _convert_boolean(self, raw: dict, out: dict, at: str, stack: tuple[str, ...]) -> None:
|
|
559
|
+
self._enum(raw, out, "boolean")
|
|
560
|
+
|
|
561
|
+
def _convert_null(self, raw: dict, out: dict, at: str, stack: tuple[str, ...]) -> None:
|
|
562
|
+
return None
|
|
563
|
+
|
|
564
|
+
@staticmethod
|
|
565
|
+
def _numeric(raw: dict, out: dict) -> None:
|
|
566
|
+
for key in ("minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum"):
|
|
567
|
+
value = raw.get(key)
|
|
568
|
+
if isinstance(value, (int, float)) and not isinstance(value, bool):
|
|
569
|
+
out[key] = value
|
|
570
|
+
|
|
571
|
+
@staticmethod
|
|
572
|
+
def _enum(raw: dict, out: dict, kind: str) -> None:
|
|
573
|
+
enum = raw.get("enum")
|
|
574
|
+
if not isinstance(enum, list) or not enum:
|
|
575
|
+
return
|
|
576
|
+
keep = [
|
|
577
|
+
v
|
|
578
|
+
for v in dict.fromkeys(_hashable(v) for v in enum)
|
|
579
|
+
if v is None or _json_type(v) == kind or (kind == "number" and _json_type(v) == "integer")
|
|
580
|
+
]
|
|
581
|
+
if keep:
|
|
582
|
+
out["enum"] = keep
|
|
583
|
+
|
|
584
|
+
def _count_dropped(self, raw: dict, out: dict) -> None:
|
|
585
|
+
for key in raw:
|
|
586
|
+
if key in out or key in ("type", "nullable", "x-nullable", "required", "allOf", "$ref"):
|
|
587
|
+
continue
|
|
588
|
+
self.dropped[key] += 1
|
|
589
|
+
|
|
590
|
+
|
|
591
|
+
def _nullable(raw: dict) -> bool:
|
|
592
|
+
return raw.get("nullable") is True or raw.get("x-nullable") is True
|
|
593
|
+
|
|
594
|
+
|
|
595
|
+
def _object_like(schema: dict) -> bool:
|
|
596
|
+
declared = schema.get("type")
|
|
597
|
+
if declared not in (None, "object"):
|
|
598
|
+
return False
|
|
599
|
+
return (
|
|
600
|
+
declared == "object"
|
|
601
|
+
or isinstance(schema.get("properties"), dict)
|
|
602
|
+
or ("allOf" not in schema and not any(k in schema for k in ("oneOf", "anyOf", "items", "enum")))
|
|
603
|
+
)
|
|
604
|
+
|
|
605
|
+
|
|
606
|
+
def _type_list(declared: Any) -> list[str]:
|
|
607
|
+
if isinstance(declared, str):
|
|
608
|
+
return [declared]
|
|
609
|
+
return [t for t in declared if isinstance(t, str)] if isinstance(declared, list) else []
|
|
610
|
+
|
|
611
|
+
|
|
612
|
+
def _json_type(value: Any) -> str:
|
|
613
|
+
if isinstance(value, bool):
|
|
614
|
+
return "boolean"
|
|
615
|
+
if isinstance(value, int):
|
|
616
|
+
return "integer"
|
|
617
|
+
if isinstance(value, float):
|
|
618
|
+
return "number"
|
|
619
|
+
if isinstance(value, str):
|
|
620
|
+
return "string"
|
|
621
|
+
if isinstance(value, dict):
|
|
622
|
+
return "object"
|
|
623
|
+
if isinstance(value, list):
|
|
624
|
+
return "array"
|
|
625
|
+
return "null"
|
|
626
|
+
|
|
627
|
+
|
|
628
|
+
def _hashable(value: Any) -> Any:
|
|
629
|
+
return value if isinstance(value, (str, int, float, bool)) or value is None else repr(value)
|