so4ag 0.1.1__py3-none-any.whl
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.
- so4ag-0.1.1.dist-info/METADATA +53 -0
- so4ag-0.1.1.dist-info/RECORD +9 -0
- so4ag-0.1.1.dist-info/WHEEL +5 -0
- so4ag-0.1.1.dist-info/entry_points.txt +2 -0
- so4ag-0.1.1.dist-info/top_level.txt +2 -0
- so4ag_profiles/__init__.py +0 -0
- so4ag_profiles/rental-0.1.json +98 -0
- so4ag_profiles/retail-0.1.json +90 -0
- so4ag_reader.py +451 -0
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: so4ag
|
|
3
|
+
Version: 0.1.1
|
|
4
|
+
Summary: Reader for SO4AG, the open format for business facts with scope, origin and validity: may this fact be used for this task now?
|
|
5
|
+
Author-email: SOQVER <info@soqver.com>
|
|
6
|
+
License-Expression: Apache-2.0
|
|
7
|
+
Project-URL: Homepage, https://soqver.com/spec/so4ag/0.1/
|
|
8
|
+
Project-URL: Repository, https://github.com/soqvercom/so4ag
|
|
9
|
+
Project-URL: Issues, https://github.com/soqvercom/so4ag/issues
|
|
10
|
+
Keywords: so4ag,ai-agents,business-facts,structured-data,json-ld,llm
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
15
|
+
Requires-Python: >=3.10
|
|
16
|
+
Description-Content-Type: text/markdown
|
|
17
|
+
|
|
18
|
+
# so4ag (Python reader)
|
|
19
|
+
|
|
20
|
+
Reader for [SO4AG](https://soqver.com/spec/so4ag/0.1/), the open format for business facts that carry their meaning,
|
|
21
|
+
scope, origin and validity. It answers one question: may this fact be used for this task at this time, and if not, why not?
|
|
22
|
+
|
|
23
|
+
Standard library only. It reads SO4AG JSON, the JSON-LD form, or an HTML page with the JSON-LD embedded.
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
pip install https://github.com/soqvercom/so4ag/releases/download/v0.1.1/so4ag-0.1.1-py3-none-any.whl
|
|
27
|
+
# examples/valid/rental-first-party.json from https://github.com/soqvercom/so4ag
|
|
28
|
+
so4ag ask rental-first-party.json --property refundableDeposit --scope vehicle_class=economy --scope branch=https://rental.example/branches/prague-airport
|
|
29
|
+
# the same question without the branch: not usable, the claim holds for one branch only
|
|
30
|
+
so4ag ask rental-first-party.json --property refundableDeposit --scope vehicle_class=economy
|
|
31
|
+
# the same question at another time
|
|
32
|
+
so4ag ask rental-first-party.json --property refundableDeposit --scope vehicle_class=economy --scope branch=https://rental.example/branches/prague-airport --now 2027-06-01T12:00:00Z
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
```python
|
|
36
|
+
import json
|
|
37
|
+
from pathlib import Path
|
|
38
|
+
from so4ag_reader import read_source, evaluate, builtin_profiles, instant
|
|
39
|
+
|
|
40
|
+
source = read_source(Path("rental-first-party.json").read_text(encoding="utf-8"))
|
|
41
|
+
task = {"property": "https://soqver.com/spec/so4ag/0.1/rental#refundableDeposit",
|
|
42
|
+
"scope": {"vehicle_class": "economy", "branch": "https://rental.example/branches/prague-airport"}}
|
|
43
|
+
for claim in source["claims"]:
|
|
44
|
+
usable, reasons, value = evaluate(claim, task, instant("2026-11-21T12:00:00Z"), builtin_profiles(),
|
|
45
|
+
source_extensions=source["extensions"])
|
|
46
|
+
print(claim["id"], usable, reasons, value)
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
A document of a version the reader does not know is refused. A review counts only when the caller says whom it trusts
|
|
50
|
+
(`--review --trust <issuer>`); a claim that needs an extension the reader does not understand is not used.
|
|
51
|
+
|
|
52
|
+
The reader passes the conformance suite of the format (`so4ag conformance spec/conformance/0.1` in a checkout of
|
|
53
|
+
https://github.com/soqvercom/so4ag). Licence: Apache-2.0.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
so4ag_reader.py,sha256=68bmU8EtKneUEU-fvSZGNcDLBd-yRKZMxdJBp3GhTcc,20070
|
|
2
|
+
so4ag_profiles/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
3
|
+
so4ag_profiles/rental-0.1.json,sha256=7-OsjpK40W2cKUhh7W0w8AzTQ2JT_I2LXm5-98i1SnE,4716
|
|
4
|
+
so4ag_profiles/retail-0.1.json,sha256=yk5EDEWpOboDOmmOnSmNpwCzGObiGX0IqwbuIHuXPmE,4410
|
|
5
|
+
so4ag-0.1.1.dist-info/METADATA,sha256=tQGM1W62vHODZY621uetAYkRQpwqDZ4jROV_fHPyuuI,2942
|
|
6
|
+
so4ag-0.1.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
7
|
+
so4ag-0.1.1.dist-info/entry_points.txt,sha256=XMabCAhMt-LZE_XrADPpO1mTu_y6oH1FgMI0-Sk0FYM,44
|
|
8
|
+
so4ag-0.1.1.dist-info/top_level.txt,sha256=WdA-dR7DV6_mz0KalGucHJLU8Spux_q9z75rKjcx7HA,28
|
|
9
|
+
so4ag-0.1.1.dist-info/RECORD,,
|
|
File without changes
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
{
|
|
2
|
+
"id": "https://soqver.com/spec/so4ag/0.1/rental",
|
|
3
|
+
"name": "SO4AG Rental",
|
|
4
|
+
"version": "0.1-draft",
|
|
5
|
+
"status": "draft",
|
|
6
|
+
"description": "Ten parameters with the highest impact for car and van rental. Every scope key restricts where a claim applies; the value any means all values of that key.",
|
|
7
|
+
"namespace": "https://soqver.com/spec/so4ag/0.1/rental#",
|
|
8
|
+
"scope_keys": {
|
|
9
|
+
"country": "ISO 3166-1 alpha-2 country code",
|
|
10
|
+
"branch": "URI of the branch (pickup location)",
|
|
11
|
+
"vehicle_class": "Vehicle class code: mini, economy, compact, intermediate, standard, fullsize, premium, suv, van, minibus, other, any",
|
|
12
|
+
"vehicle": "Specific vehicle model as named by the publisher (e.g. Škoda Kamiq DSG). Narrows a claim to that vehicle",
|
|
13
|
+
"rental_days": "Number of rental days the price applies to (integer as string)",
|
|
14
|
+
"payment_purpose": "deposit | payment",
|
|
15
|
+
"tariff": "Publisher-defined tariff code",
|
|
16
|
+
"period_from": "Start of the rental period the claim applies to (ISO 8601 date-time)",
|
|
17
|
+
"period_until": "End of the rental period the claim applies to (ISO 8601 date-time)",
|
|
18
|
+
"customer": "Customer segment: private, business, any"
|
|
19
|
+
},
|
|
20
|
+
"properties": {
|
|
21
|
+
"operator": {
|
|
22
|
+
"label": {"en": "Operator", "cs": "Provozovatel"},
|
|
23
|
+
"value_types": ["organization"],
|
|
24
|
+
"required_scope": [],
|
|
25
|
+
"max_validity": "P400D",
|
|
26
|
+
"description": "Legal entity operating the rental. Identifiers SHOULD include a registry number (cz-ico, sk-ico, lei)."
|
|
27
|
+
},
|
|
28
|
+
"branch": {
|
|
29
|
+
"label": {"en": "Branch", "cs": "Pobočka"},
|
|
30
|
+
"value_types": ["place"],
|
|
31
|
+
"required_scope": [],
|
|
32
|
+
"max_validity": "P180D",
|
|
33
|
+
"description": "Pickup location with address and optional opening hours. The claim subject is the branch URI."
|
|
34
|
+
},
|
|
35
|
+
"totalPrice": {
|
|
36
|
+
"label": {"en": "Total price", "cs": "Celková cena"},
|
|
37
|
+
"value_types": ["money"],
|
|
38
|
+
"required_scope": ["branch", "vehicle_class", "rental_days"],
|
|
39
|
+
"max_validity": "P7D",
|
|
40
|
+
"description": "Total price for the whole rental of rental_days days including all mandatory fees and VAT."
|
|
41
|
+
},
|
|
42
|
+
"refundableDeposit": {
|
|
43
|
+
"label": {"en": "Refundable deposit", "cs": "Vratná kauce"},
|
|
44
|
+
"value_types": ["money"],
|
|
45
|
+
"required_scope": ["branch", "vehicle_class"],
|
|
46
|
+
"max_validity": "P60D",
|
|
47
|
+
"description": "Amount blocked or paid as a refundable security deposit. Never a rental price."
|
|
48
|
+
},
|
|
49
|
+
"mileageLimit": {
|
|
50
|
+
"label": {"en": "Mileage limit", "cs": "Limit kilometrů"},
|
|
51
|
+
"value_types": ["quantity", "enum"],
|
|
52
|
+
"units": ["km/d", "km"],
|
|
53
|
+
"enum": ["unlimited"],
|
|
54
|
+
"required_scope": ["vehicle_class"],
|
|
55
|
+
"max_validity": "P60D",
|
|
56
|
+
"description": "Included distance per day (km/d) or per rental (km), or the code unlimited."
|
|
57
|
+
},
|
|
58
|
+
"acceptedPaymentMethods": {
|
|
59
|
+
"label": {"en": "Accepted payment methods", "cs": "Přijímané platby"},
|
|
60
|
+
"value_types": ["enum_set"],
|
|
61
|
+
"enum": ["credit_card", "debit_card", "cash", "bank_transfer", "apple_pay", "google_pay", "invoice"],
|
|
62
|
+
"required_scope": ["payment_purpose"],
|
|
63
|
+
"max_validity": "P90D",
|
|
64
|
+
"description": "Methods accepted for the given purpose. Deposit and payment are separate claims."
|
|
65
|
+
},
|
|
66
|
+
"minimumDriverAge": {
|
|
67
|
+
"label": {"en": "Minimum driver age", "cs": "Minimální věk řidiče"},
|
|
68
|
+
"value_types": ["quantity"],
|
|
69
|
+
"units": ["a"],
|
|
70
|
+
"required_scope": ["vehicle_class"],
|
|
71
|
+
"max_validity": "P180D",
|
|
72
|
+
"description": "Minimum driver age in years (unit a)."
|
|
73
|
+
},
|
|
74
|
+
"additionalDriverFee": {
|
|
75
|
+
"label": {"en": "Additional driver fee", "cs": "Poplatek za dalšího řidiče"},
|
|
76
|
+
"value_types": ["money"],
|
|
77
|
+
"required_scope": [],
|
|
78
|
+
"max_validity": "P90D",
|
|
79
|
+
"description": "Fee for one additional driver per rental. 0.00 means free. If additional drivers are not allowed, knowledge_state is not_applicable."
|
|
80
|
+
},
|
|
81
|
+
"freeCancellation": {
|
|
82
|
+
"label": {"en": "Free cancellation", "cs": "Storno zdarma"},
|
|
83
|
+
"value_types": ["quantity", "text"],
|
|
84
|
+
"units": ["h"],
|
|
85
|
+
"required_scope": [],
|
|
86
|
+
"max_validity": "P90D",
|
|
87
|
+
"description": "Hours before pickup until which cancellation is free (unit h), or a short text when the rule cannot be expressed as hours."
|
|
88
|
+
},
|
|
89
|
+
"availability": {
|
|
90
|
+
"label": {"en": "Availability", "cs": "Dostupnost"},
|
|
91
|
+
"value_types": ["boolean"],
|
|
92
|
+
"required_scope": ["branch", "vehicle_class", "period_from", "period_until"],
|
|
93
|
+
"max_validity": "PT1H",
|
|
94
|
+
"live": true,
|
|
95
|
+
"description": "Whether a vehicle of the class is available for the period. Live data: validity at most one hour. Without a live connection the claim MUST be unknown."
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
}
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
{
|
|
2
|
+
"id": "https://soqver.com/spec/so4ag/0.1/retail",
|
|
3
|
+
"name": "SO4AG Retail",
|
|
4
|
+
"version": "0.1-draft",
|
|
5
|
+
"status": "draft",
|
|
6
|
+
"description": "Ten parameters a customer asks about before ordering from an online shop: delivery, payment, returns. Every scope key restricts where a claim applies; the value any means all values of that key.",
|
|
7
|
+
"namespace": "https://soqver.com/spec/so4ag/0.1/retail#",
|
|
8
|
+
"scope_keys": {
|
|
9
|
+
"country": "ISO 3166-1 alpha-2 code of the delivery country",
|
|
10
|
+
"delivery_method": "Delivery method code: courier, pickup_point, parcel_locker, post, store_pickup, any",
|
|
11
|
+
"branch": "URI of the store or pickup place",
|
|
12
|
+
"customer": "Customer segment: private, business, any"
|
|
13
|
+
},
|
|
14
|
+
"properties": {
|
|
15
|
+
"operator": {
|
|
16
|
+
"label": {"en": "Operator", "cs": "Provozovatel"},
|
|
17
|
+
"value_types": ["organization"],
|
|
18
|
+
"required_scope": [],
|
|
19
|
+
"max_validity": "P400D",
|
|
20
|
+
"description": "Legal entity operating the shop. Identifiers SHOULD include a registry number (cz-ico, sk-ico, lei)."
|
|
21
|
+
},
|
|
22
|
+
"branch": {
|
|
23
|
+
"label": {"en": "Store or pickup place", "cs": "Prodejna nebo výdejní místo"},
|
|
24
|
+
"value_types": ["place"],
|
|
25
|
+
"required_scope": [],
|
|
26
|
+
"max_validity": "P180D",
|
|
27
|
+
"description": "The shop's own store or pickup place with address and optional opening hours. The claim subject is the place URI."
|
|
28
|
+
},
|
|
29
|
+
"shippingPrice": {
|
|
30
|
+
"label": {"en": "Shipping price", "cs": "Cena dopravy"},
|
|
31
|
+
"value_types": ["money"],
|
|
32
|
+
"required_scope": ["country", "delivery_method"],
|
|
33
|
+
"max_validity": "P60D",
|
|
34
|
+
"description": "Price of delivering a standard parcel including VAT. With bound = minimum the shop states a starting price. Oversized goods and cash-on-delivery fees are not part of this claim."
|
|
35
|
+
},
|
|
36
|
+
"freeShippingFrom": {
|
|
37
|
+
"label": {"en": "Free shipping from", "cs": "Doprava zdarma od"},
|
|
38
|
+
"value_types": ["money"],
|
|
39
|
+
"required_scope": ["country"],
|
|
40
|
+
"max_validity": "P60D",
|
|
41
|
+
"description": "Order value from which standard shipping is free. If the shop never offers free shipping, knowledge_state is not_applicable. Free shipping without a threshold is amount 0.00."
|
|
42
|
+
},
|
|
43
|
+
"deliveryTime": {
|
|
44
|
+
"label": {"en": "Delivery time", "cs": "Dodací lhůta"},
|
|
45
|
+
"value_types": ["quantity", "text"],
|
|
46
|
+
"units": ["d"],
|
|
47
|
+
"required_scope": ["country"],
|
|
48
|
+
"max_validity": "P60D",
|
|
49
|
+
"description": "Usual number of working days from order to delivery for goods in stock (unit d), or a short text when the rule cannot be expressed as days. Never a guarantee for a specific order."
|
|
50
|
+
},
|
|
51
|
+
"paymentMethods": {
|
|
52
|
+
"label": {"en": "Payment methods", "cs": "Způsoby platby"},
|
|
53
|
+
"value_types": ["enum_set"],
|
|
54
|
+
"enum": ["card_online", "bank_transfer", "cash_on_delivery", "cash", "apple_pay", "google_pay", "invoice", "installments"],
|
|
55
|
+
"required_scope": [],
|
|
56
|
+
"max_validity": "P90D",
|
|
57
|
+
"description": "Payment methods the shop accepts. cash_on_delivery = payment to the carrier on delivery; cash = payment in the shop's own store."
|
|
58
|
+
},
|
|
59
|
+
"cashOnDeliveryFee": {
|
|
60
|
+
"label": {"en": "Cash on delivery fee", "cs": "Poplatek za dobírku"},
|
|
61
|
+
"value_types": ["money"],
|
|
62
|
+
"required_scope": [],
|
|
63
|
+
"max_validity": "P60D",
|
|
64
|
+
"description": "Extra fee for paying on delivery. 0.00 means free. If the shop does not offer cash on delivery, knowledge_state is not_applicable."
|
|
65
|
+
},
|
|
66
|
+
"returnPeriod": {
|
|
67
|
+
"label": {"en": "Return period", "cs": "Lhůta pro vrácení zboží"},
|
|
68
|
+
"value_types": ["quantity"],
|
|
69
|
+
"units": ["d"],
|
|
70
|
+
"required_scope": [],
|
|
71
|
+
"max_validity": "P180D",
|
|
72
|
+
"description": "Number of days from delivery within which a consumer may return goods without giving a reason (unit d)."
|
|
73
|
+
},
|
|
74
|
+
"warrantyPeriod": {
|
|
75
|
+
"label": {"en": "Warranty period", "cs": "Záruční doba"},
|
|
76
|
+
"value_types": ["quantity"],
|
|
77
|
+
"units": ["mo"],
|
|
78
|
+
"required_scope": [],
|
|
79
|
+
"max_validity": "P180D",
|
|
80
|
+
"description": "Warranty or liability period for new goods sold to consumers in months (unit mo)."
|
|
81
|
+
},
|
|
82
|
+
"storePickup": {
|
|
83
|
+
"label": {"en": "Pickup in store", "cs": "Osobní odběr"},
|
|
84
|
+
"value_types": ["boolean"],
|
|
85
|
+
"required_scope": [],
|
|
86
|
+
"max_validity": "P90D",
|
|
87
|
+
"description": "Whether an order can be collected in person at the shop's own store or pickup place."
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
}
|
so4ag_reader.py
ADDED
|
@@ -0,0 +1,451 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Second SO4AG 0.1 reader (Python, standard library only, Apache-2.0).
|
|
3
|
+
|
|
4
|
+
Written separately from the reference implementation in validator/ and shares no code with it.
|
|
5
|
+
It reads a source from SO4AG JSON, from a JSON-LD document or from an HTML page with embedded JSON-LD,
|
|
6
|
+
and answers one question: may this claim be used for this task at this time?
|
|
7
|
+
|
|
8
|
+
python so4ag_reader.py conformance <dir> run the conformance suite
|
|
9
|
+
python so4ag_reader.py ask <file> --property <uri-or-name> [--scope k=v ...] [--now ISO]
|
|
10
|
+
[--review --trust <issuer-uri> ...] [--extension <uri> ...]
|
|
11
|
+
|
|
12
|
+
A document of a version this reader does not know is refused, never read by the rules of another version.
|
|
13
|
+
--review without --trust accepts nothing: a matching digest ties an attestation to the wording of a claim,
|
|
14
|
+
it says nothing about who issued it. Whom to trust is the decision of the consumer.
|
|
15
|
+
"""
|
|
16
|
+
import hashlib
|
|
17
|
+
import json
|
|
18
|
+
import re
|
|
19
|
+
import sys
|
|
20
|
+
from datetime import datetime, timezone
|
|
21
|
+
from pathlib import Path
|
|
22
|
+
|
|
23
|
+
SOURCE_TYPES = ("so4ag:Source", "https://soqver.com/spec/so4ag/0.1/terms#Source")
|
|
24
|
+
SUPPORTED_VERSIONS = ("0.1-draft", "0.2-draft")
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class UnsupportedVersion(ValueError):
|
|
28
|
+
"""The document says it is another version of the format (or says no version at all)."""
|
|
29
|
+
|
|
30
|
+
def __init__(self, code, version):
|
|
31
|
+
super().__init__(code + (": " + str(version) if version is not None else ""))
|
|
32
|
+
self.code, self.version = code, version
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
# ---------- canonical JSON (RFC 8785 for the values SO4AG uses) and claim digest ----------
|
|
36
|
+
def canonical(v):
|
|
37
|
+
if isinstance(v, dict):
|
|
38
|
+
keys = sorted(v, key=lambda k: k.encode("utf-16-be"))
|
|
39
|
+
return "{" + ",".join(json.dumps(k, ensure_ascii=False) + ":" + canonical(v[k]) for k in keys) + "}"
|
|
40
|
+
if isinstance(v, list):
|
|
41
|
+
return "[" + ",".join(canonical(x) for x in v) + "]"
|
|
42
|
+
if isinstance(v, bool) or v is None or isinstance(v, str):
|
|
43
|
+
return json.dumps(v, ensure_ascii=False)
|
|
44
|
+
if isinstance(v, (int, float)):
|
|
45
|
+
return es_number(v)
|
|
46
|
+
raise ValueError("value cannot be canonicalised")
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def es_number(x):
|
|
50
|
+
"""A number written the way ECMAScript writes it, which is what RFC 8785 requires (0.000001, 1e-7, 1e+21)."""
|
|
51
|
+
if isinstance(x, int) and abs(x) < 2 ** 53:
|
|
52
|
+
return str(x)
|
|
53
|
+
x = float(x)
|
|
54
|
+
if x != x or x in (float("inf"), float("-inf")):
|
|
55
|
+
raise ValueError("non-finite number")
|
|
56
|
+
if x == 0:
|
|
57
|
+
return "0"
|
|
58
|
+
sign, x = ("-" if x < 0 else ""), abs(x)
|
|
59
|
+
mantissa, _, exponent = repr(x).partition("e")
|
|
60
|
+
whole, _, frac = mantissa.partition(".")
|
|
61
|
+
digits = whole + frac
|
|
62
|
+
point = len(whole) + (int(exponent) if exponent else 0) # value = 0.digits * 10 ** point
|
|
63
|
+
lead = len(digits) - len(digits.lstrip("0"))
|
|
64
|
+
digits, point = digits[lead:].rstrip("0"), point - lead
|
|
65
|
+
k = len(digits)
|
|
66
|
+
if k <= point <= 21:
|
|
67
|
+
return sign + digits + "0" * (point - k)
|
|
68
|
+
if 0 < point <= 21:
|
|
69
|
+
return sign + digits[:point] + "." + digits[point:]
|
|
70
|
+
if -6 < point <= 0:
|
|
71
|
+
return sign + "0." + "0" * (-point) + digits
|
|
72
|
+
e = point - 1
|
|
73
|
+
return sign + digits[0] + ("." + digits[1:] if k > 1 else "") + "e" + ("+" if e >= 0 else "-") + str(abs(e))
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def claim_digest(claim):
|
|
77
|
+
body = {k: v for k, v in claim.items() if k != "attestations"}
|
|
78
|
+
return "sha256:" + hashlib.sha256(canonical(body).encode("utf-8")).hexdigest()
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
# ---------- time ----------
|
|
82
|
+
def instant(text):
|
|
83
|
+
t = datetime.fromisoformat(text.replace("Z", "+00:00"))
|
|
84
|
+
return t if t.tzinfo else t.replace(tzinfo=timezone.utc)
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
# ---------- the consumer rules ----------
|
|
88
|
+
def scope_keys_of(property_uri, profiles):
|
|
89
|
+
for p in profiles:
|
|
90
|
+
ns = p["namespace"]
|
|
91
|
+
if property_uri.startswith(ns) and property_uri[len(ns):] in p["properties"]:
|
|
92
|
+
return set(p.get("scope_keys", {}))
|
|
93
|
+
return set()
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def evaluate(claim, task, now, profiles, source_extensions=None, known_extensions=()):
|
|
97
|
+
"""Returns (usable, reasons, value). `disputed` is reported but does not block.
|
|
98
|
+
known_extensions: URIs of the extensions this consumer implements; source_extensions: `extensions` of the whole source."""
|
|
99
|
+
reasons = []
|
|
100
|
+
for uri, ext in list((source_extensions or {}).items()) + list((claim.get("extensions") or {}).items()):
|
|
101
|
+
if isinstance(ext, dict) and ext.get("affects_use") is True and uri not in known_extensions:
|
|
102
|
+
reasons.append("unknown_required_extension:" + uri)
|
|
103
|
+
if task.get("property") and task["property"] != claim["property"]:
|
|
104
|
+
reasons.append("property_mismatch")
|
|
105
|
+
if task.get("subject") and task["subject"] != claim["subject"]:
|
|
106
|
+
reasons.append("subject_mismatch")
|
|
107
|
+
understood = set(task["understoodScopeKeys"]) if "understoodScopeKeys" in task else scope_keys_of(claim["property"], profiles)
|
|
108
|
+
asked = task.get("scope") or {}
|
|
109
|
+
for key, limit in claim["scope"].items():
|
|
110
|
+
if key not in understood:
|
|
111
|
+
reasons.append("scope_not_comparable:" + key)
|
|
112
|
+
elif key not in asked:
|
|
113
|
+
reasons.append("scope_not_in_task:" + key)
|
|
114
|
+
elif limit != "any" and scope_text(asked[key]) != limit:
|
|
115
|
+
reasons.append("scope_mismatch:" + key)
|
|
116
|
+
if now < instant(claim["valid_from"]):
|
|
117
|
+
reasons.append("not_yet_valid")
|
|
118
|
+
if now >= instant(claim["valid_until"]):
|
|
119
|
+
reasons.append("expired")
|
|
120
|
+
if claim.get("dispute"):
|
|
121
|
+
reasons.append("disputed")
|
|
122
|
+
if claim["knowledge_state"] != "known":
|
|
123
|
+
reasons.append(claim["knowledge_state"])
|
|
124
|
+
if task.get("requireReview"):
|
|
125
|
+
trusted = task.get("trustedIssuers")
|
|
126
|
+
if not isinstance(trusted, list):
|
|
127
|
+
reasons.append("no_trust_policy") # without the consumer's own list nothing is independently reviewed
|
|
128
|
+
else:
|
|
129
|
+
digest = claim_digest(claim)
|
|
130
|
+
accepted = any(
|
|
131
|
+
a.get("claim_digest") == digest
|
|
132
|
+
and a.get("issuer_relation") == "independent"
|
|
133
|
+
and a.get("issuer") in trusted
|
|
134
|
+
and instant(a["issued_at"]) <= now < instant(a["expires_at"])
|
|
135
|
+
for a in claim.get("attestations", [])
|
|
136
|
+
)
|
|
137
|
+
if not accepted:
|
|
138
|
+
reasons.append("no_valid_independent_attestation")
|
|
139
|
+
usable = all(r == "disputed" for r in reasons)
|
|
140
|
+
return usable, sorted(reasons), (claim.get("value") if usable else None)
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
def scope_text(v):
|
|
144
|
+
if isinstance(v, bool):
|
|
145
|
+
return "true" if v else "false"
|
|
146
|
+
if isinstance(v, float) and v == int(v):
|
|
147
|
+
return str(int(v))
|
|
148
|
+
return str(v)
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
# ---------- reading JSON-LD ----------
|
|
152
|
+
def identifiers(node_list):
|
|
153
|
+
return [{"scheme": i["propertyID"], "value": i["value"]} for i in node_list]
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
def value_from_node(n):
|
|
157
|
+
if isinstance(n, bool):
|
|
158
|
+
return {"type": "boolean", "value": n}
|
|
159
|
+
if "@value" in n:
|
|
160
|
+
out = {"type": "text", "value": n["@value"]}
|
|
161
|
+
if "@language" in n:
|
|
162
|
+
out["lang"] = n["@language"]
|
|
163
|
+
return out
|
|
164
|
+
kind = n.get("@type")
|
|
165
|
+
if kind == "MonetaryAmount":
|
|
166
|
+
out = {"type": "money", "amount": n["minValue"] if "minValue" in n else n["value"], "currency": n["currency"]}
|
|
167
|
+
if "so4ag:vatIncluded" in n:
|
|
168
|
+
out["vat_included"] = n["so4ag:vatIncluded"]
|
|
169
|
+
if "minValue" in n:
|
|
170
|
+
out["bound"] = "minimum"
|
|
171
|
+
elif "so4ag:bound" in n:
|
|
172
|
+
out["bound"] = n["so4ag:bound"]
|
|
173
|
+
return out
|
|
174
|
+
if kind == "QuantitativeValue":
|
|
175
|
+
return {"type": "quantity", "value": n["value"], "unit": n["unitText"]}
|
|
176
|
+
if kind == "DefinedTerm":
|
|
177
|
+
return {"type": "enum", "value": n["termCode"]}
|
|
178
|
+
if kind == "ItemList":
|
|
179
|
+
return {"type": "enum_set", "values": [x["termCode"] for x in n["itemListElement"]]}
|
|
180
|
+
if kind == "Organization":
|
|
181
|
+
out = {"type": "organization", "name": n["name"]}
|
|
182
|
+
if "identifier" in n:
|
|
183
|
+
out["identifiers"] = identifiers(n["identifier"])
|
|
184
|
+
if "url" in n:
|
|
185
|
+
out["url"] = n["url"]
|
|
186
|
+
return out
|
|
187
|
+
if kind == "Place":
|
|
188
|
+
out = {"type": "place", "name": n["name"]}
|
|
189
|
+
address = n.get("address") or {}
|
|
190
|
+
if "streetAddress" in address:
|
|
191
|
+
out["address"] = address["streetAddress"]
|
|
192
|
+
if "addressCountry" in address:
|
|
193
|
+
out["country"] = address["addressCountry"]
|
|
194
|
+
if "geo" in n:
|
|
195
|
+
out["geo"] = {"lat": n["geo"]["latitude"], "lon": n["geo"]["longitude"]}
|
|
196
|
+
if "openingHours" in n:
|
|
197
|
+
out["opening_hours"] = n["openingHours"]
|
|
198
|
+
return out
|
|
199
|
+
raise ValueError("unknown value node")
|
|
200
|
+
|
|
201
|
+
|
|
202
|
+
def copy_fields(src, pairs):
|
|
203
|
+
return {to: src[frm] for frm, to in pairs if frm in src}
|
|
204
|
+
|
|
205
|
+
|
|
206
|
+
def claim_from_node(pv, subject):
|
|
207
|
+
c = {"id": pv["@id"], "subject": subject, "property": pv["propertyID"],
|
|
208
|
+
"knowledge_state": pv["so4ag:knowledgeState"], "assertion_basis": pv["so4ag:assertionBasis"],
|
|
209
|
+
"valid_from": pv["validFrom"], "valid_until": pv["validThrough"],
|
|
210
|
+
"scope": {s["propertyID"]: s["value"] for s in pv.get("so4ag:scope", [])}}
|
|
211
|
+
if "so4ag:revision" in pv:
|
|
212
|
+
c["revision"] = pv["so4ag:revision"]
|
|
213
|
+
if "value" in pv:
|
|
214
|
+
c["value"] = value_from_node(pv["value"])
|
|
215
|
+
if "so4ag:evidence" in pv:
|
|
216
|
+
c["evidence"] = [copy_fields(e, [("url", "url"), ("so4ag:observedAt", "observed_at"), ("so4ag:kind", "kind"),
|
|
217
|
+
("so4ag:issuer", "issuer"), ("so4ag:quote", "quote"), ("so4ag:digest", "digest")])
|
|
218
|
+
for e in pv["so4ag:evidence"]]
|
|
219
|
+
if "so4ag:note" in pv:
|
|
220
|
+
c["note"] = pv["so4ag:note"]
|
|
221
|
+
if "so4ag:dispute" in pv:
|
|
222
|
+
d = pv["so4ag:dispute"]
|
|
223
|
+
c["dispute"] = copy_fields(d, [("so4ag:since", "since"), ("so4ag:note", "note")])
|
|
224
|
+
if "so4ag:conflictingClaim" in d:
|
|
225
|
+
c["dispute"]["conflicting_claims"] = [x["@id"] for x in d["so4ag:conflictingClaim"]]
|
|
226
|
+
if "so4ag:attestation" in pv:
|
|
227
|
+
c["attestations"] = []
|
|
228
|
+
for a in pv["so4ag:attestation"]:
|
|
229
|
+
item = copy_fields(a, [("@id", "id"), ("so4ag:issuerRelation", "issuer_relation"), ("so4ag:method", "method"),
|
|
230
|
+
("so4ag:claimDigest", "claim_digest"), ("so4ag:issuedAt", "issued_at"),
|
|
231
|
+
("so4ag:expiresAt", "expires_at"), ("so4ag:statusUrl", "status_url"),
|
|
232
|
+
("so4ag:credentialUrl", "credential_url")])
|
|
233
|
+
if "so4ag:issuer" in a:
|
|
234
|
+
item["issuer"] = a["so4ag:issuer"]["@id"]
|
|
235
|
+
c["attestations"].append(item)
|
|
236
|
+
if "so4ag:extensions" in pv:
|
|
237
|
+
c["extensions"] = pv["so4ag:extensions"]["@value"]
|
|
238
|
+
return c
|
|
239
|
+
|
|
240
|
+
|
|
241
|
+
def check_version(version):
|
|
242
|
+
if version is None:
|
|
243
|
+
raise UnsupportedVersion("missing_version", None)
|
|
244
|
+
if version not in SUPPORTED_VERSIONS:
|
|
245
|
+
raise UnsupportedVersion("unsupported_version", version)
|
|
246
|
+
return version
|
|
247
|
+
|
|
248
|
+
|
|
249
|
+
def source_from_jsonld(doc):
|
|
250
|
+
"""JSON-LD -> {"version", "claims", "extensions"}; refuses a source of another version."""
|
|
251
|
+
graph = doc.get("@graph")
|
|
252
|
+
if not isinstance(graph, list):
|
|
253
|
+
raise ValueError("not a SO4AG source")
|
|
254
|
+
head = next((n for n in graph if n.get("additionalType") in SOURCE_TYPES), None)
|
|
255
|
+
if head is None:
|
|
256
|
+
raise ValueError("not a SO4AG source")
|
|
257
|
+
version = check_version(head.get("so4ag:version"))
|
|
258
|
+
extensions = (head.get("so4ag:extensions") or {}).get("@value")
|
|
259
|
+
return {"version": version, "claims": claims_from_jsonld(doc), "extensions": extensions}
|
|
260
|
+
|
|
261
|
+
|
|
262
|
+
def claims_from_jsonld(doc):
|
|
263
|
+
graph = doc.get("@graph")
|
|
264
|
+
if not isinstance(graph, list) or not any(n.get("additionalType") in SOURCE_TYPES for n in graph):
|
|
265
|
+
raise ValueError("not a SO4AG source")
|
|
266
|
+
claims = []
|
|
267
|
+
for node in graph:
|
|
268
|
+
if node.get("additionalType") in SOURCE_TYPES:
|
|
269
|
+
continue
|
|
270
|
+
for pv in node.get("additionalProperty", []):
|
|
271
|
+
if "so4ag:knowledgeState" in pv:
|
|
272
|
+
claims.append(claim_from_node(pv, node["@id"]))
|
|
273
|
+
return claims
|
|
274
|
+
|
|
275
|
+
|
|
276
|
+
DEFAULT_KEYS = ("subject", "assertion_basis", "valid_from", "valid_until", "evidence", "scope")
|
|
277
|
+
|
|
278
|
+
|
|
279
|
+
def expand02(doc):
|
|
280
|
+
"""SO4AG 0.2 -> claims written out in full: file defaults applied, null = the claim has no such field."""
|
|
281
|
+
defaults = doc.get("defaults") or {}
|
|
282
|
+
out = []
|
|
283
|
+
for claim in doc.get("claims", []):
|
|
284
|
+
c = dict(claim)
|
|
285
|
+
for k in DEFAULT_KEYS:
|
|
286
|
+
if k in c and c[k] is None:
|
|
287
|
+
del c[k]
|
|
288
|
+
elif k not in c and k in defaults:
|
|
289
|
+
c[k] = json.loads(json.dumps(defaults[k]))
|
|
290
|
+
c.setdefault("scope", {})
|
|
291
|
+
out.append(c)
|
|
292
|
+
return out
|
|
293
|
+
|
|
294
|
+
|
|
295
|
+
def read_source(text):
|
|
296
|
+
"""SO4AG JSON (0.1 or 0.2), JSON-LD, or an HTML page with JSON-LD blocks -> {"version", "claims", "extensions"}.
|
|
297
|
+
Raises UnsupportedVersion when the document is of a version this reader does not implement."""
|
|
298
|
+
stripped = text.lstrip()
|
|
299
|
+
if stripped.startswith("{"):
|
|
300
|
+
doc = json.loads(text)
|
|
301
|
+
if "@graph" in doc:
|
|
302
|
+
return source_from_jsonld(doc)
|
|
303
|
+
version = check_version(doc.get("so4ag"))
|
|
304
|
+
claims = expand02(doc) if version == "0.2-draft" else doc["claims"]
|
|
305
|
+
return {"version": version, "claims": claims, "extensions": doc.get("extensions")}
|
|
306
|
+
for block in re.findall(r'<script\b[^>]*type\s*=\s*["\']application/ld\+json["\'][^>]*>(.*?)</script>', text, re.S | re.I):
|
|
307
|
+
try:
|
|
308
|
+
doc = json.loads(block)
|
|
309
|
+
except ValueError:
|
|
310
|
+
continue
|
|
311
|
+
for d in doc if isinstance(doc, list) else [doc]:
|
|
312
|
+
try:
|
|
313
|
+
return source_from_jsonld(d)
|
|
314
|
+
except UnsupportedVersion:
|
|
315
|
+
raise
|
|
316
|
+
except (ValueError, AttributeError):
|
|
317
|
+
pass
|
|
318
|
+
raise ValueError("no SO4AG source found")
|
|
319
|
+
|
|
320
|
+
|
|
321
|
+
def claims_from_text(text):
|
|
322
|
+
"""The claims of a source of a supported version (see read_source for the extensions of the source)."""
|
|
323
|
+
return read_source(text)["claims"]
|
|
324
|
+
|
|
325
|
+
|
|
326
|
+
# ---------- command line ----------
|
|
327
|
+
def load_profiles(root):
|
|
328
|
+
return [json.loads(p.read_text(encoding="utf-8")) for p in sorted(Path(root).glob("*.json"))]
|
|
329
|
+
|
|
330
|
+
|
|
331
|
+
def builtin_profiles():
|
|
332
|
+
"""Profiles of the format: from the repository when run from a checkout, otherwise the copies installed with the package."""
|
|
333
|
+
here = Path(__file__).resolve().parent
|
|
334
|
+
for root in (here.parent.parent / "spec" / "profiles", here / "so4ag_profiles"):
|
|
335
|
+
found = load_profiles(root)
|
|
336
|
+
if found:
|
|
337
|
+
return found
|
|
338
|
+
return []
|
|
339
|
+
|
|
340
|
+
|
|
341
|
+
def run_conformance(folder):
|
|
342
|
+
folder = Path(folder)
|
|
343
|
+
profiles = load_profiles(folder.parent.parent / "profiles")
|
|
344
|
+
failed = total = 0
|
|
345
|
+
|
|
346
|
+
def check(ok, label):
|
|
347
|
+
nonlocal failed, total
|
|
348
|
+
total += 1
|
|
349
|
+
if not ok:
|
|
350
|
+
failed += 1
|
|
351
|
+
print("FAIL", label)
|
|
352
|
+
|
|
353
|
+
digests = json.loads((folder / "digests.json").read_text(encoding="utf-8"))
|
|
354
|
+
sources = {}
|
|
355
|
+
for name in ("shop", "rental"):
|
|
356
|
+
native = json.loads((folder / f"{name}.json").read_text(encoding="utf-8"))["claims"]
|
|
357
|
+
from_ld = claims_from_text((folder / f"{name}.jsonld").read_text(encoding="utf-8"))
|
|
358
|
+
html = '<html><head><script type="application/ld+json">' + (folder / f"{name}.jsonld").read_text(encoding="utf-8") + "</script></head></html>"
|
|
359
|
+
from_html = claims_from_text(html)
|
|
360
|
+
sources[name + ".json"] = {"so4ag": native, "jsonld": from_ld, "html": from_html}
|
|
361
|
+
for form, claims in sources[name + ".json"].items():
|
|
362
|
+
check(len(claims) == len(native), f"{name} {form}: number of claims")
|
|
363
|
+
for c in claims:
|
|
364
|
+
check(claim_digest(c) == digests.get(c["id"]), f"{name} {form}: digest of {c['id']}")
|
|
365
|
+
cases = json.loads((folder / "evaluation.json").read_text(encoding="utf-8"))["cases"]
|
|
366
|
+
for case in cases:
|
|
367
|
+
for form, claims in sources[case["manifest"]].items():
|
|
368
|
+
claim = next(c for c in claims if c["id"] == case["claim"])
|
|
369
|
+
usable, reasons, value = evaluate(claim, case["task"], instant(case["now"]), profiles,
|
|
370
|
+
known_extensions=case.get("knownExtensions", ()))
|
|
371
|
+
want = case["expect"]
|
|
372
|
+
check(usable == want["usable"] and reasons == want["reasons"] and value == want["value"],
|
|
373
|
+
f"{case['id']} ({form}) {case['title']}: got {usable} {reasons}")
|
|
374
|
+
# whole sources: version of the format and extensions of the source; canonical form of numbers and strings
|
|
375
|
+
extra = folder / "sources.json"
|
|
376
|
+
n_sources = n_vectors = 0
|
|
377
|
+
if extra.exists():
|
|
378
|
+
for case in json.loads(extra.read_text(encoding="utf-8"))["cases"]:
|
|
379
|
+
n_sources += 1
|
|
380
|
+
want = case["expect"]
|
|
381
|
+
try:
|
|
382
|
+
src = read_source(json.dumps(case["document"]))
|
|
383
|
+
except UnsupportedVersion as err:
|
|
384
|
+
check(want.get("error") == err.code, f"{case['id']} {case['title']}: got {err.code}")
|
|
385
|
+
continue
|
|
386
|
+
if "error" in want:
|
|
387
|
+
check(False, f"{case['id']} {case['title']}: the source was read, {want['error']} expected")
|
|
388
|
+
continue
|
|
389
|
+
for c in src["claims"]:
|
|
390
|
+
usable, reasons, _ = evaluate(c, {"property": c["property"], "scope": c["scope"]}, instant(case["now"]), profiles,
|
|
391
|
+
source_extensions=src["extensions"], known_extensions=case.get("knownExtensions", ()))
|
|
392
|
+
check(usable == want["usable"] and all(r in reasons for r in want.get("reasons", [])), f"{case['id']} {case['title']}: got {usable} {reasons}")
|
|
393
|
+
vectors = folder / "canonical.json"
|
|
394
|
+
if vectors.exists():
|
|
395
|
+
for vec in json.loads(vectors.read_text(encoding="utf-8"))["vectors"]:
|
|
396
|
+
n_vectors += 1
|
|
397
|
+
check(canonical(vec["value"]) == vec["canonical"], f"canonical form of {vec['canonical']}: got {canonical(vec['value'])}")
|
|
398
|
+
print(f"{total - failed}/{total} checks passed ({len(cases)} evaluation cases x 3 input forms, digests of every claim, "
|
|
399
|
+
f"{n_sources} whole-source cases, {n_vectors} canonical vectors)")
|
|
400
|
+
return 1 if failed else 0
|
|
401
|
+
|
|
402
|
+
|
|
403
|
+
def run_ask(argv):
|
|
404
|
+
path, prop, scope, now, review, trust, known = argv[0], None, {}, datetime.now(timezone.utc), False, None, []
|
|
405
|
+
i = 1
|
|
406
|
+
while i < len(argv):
|
|
407
|
+
if argv[i] == "--property":
|
|
408
|
+
prop = argv[i + 1]; i += 2
|
|
409
|
+
elif argv[i] == "--scope":
|
|
410
|
+
k, _, v = argv[i + 1].partition("="); scope[k] = v; i += 2
|
|
411
|
+
elif argv[i] == "--now":
|
|
412
|
+
now = instant(argv[i + 1]); i += 2
|
|
413
|
+
elif argv[i] == "--review":
|
|
414
|
+
review = True; i += 1
|
|
415
|
+
elif argv[i] == "--trust":
|
|
416
|
+
trust = (trust or []) + [argv[i + 1]]; i += 2
|
|
417
|
+
elif argv[i] == "--extension":
|
|
418
|
+
known.append(argv[i + 1]); i += 2
|
|
419
|
+
else:
|
|
420
|
+
raise SystemExit("unknown argument " + argv[i])
|
|
421
|
+
profiles = builtin_profiles()
|
|
422
|
+
try:
|
|
423
|
+
source = read_source(Path(path).read_text(encoding="utf-8"))
|
|
424
|
+
except UnsupportedVersion as err:
|
|
425
|
+
print(json.dumps({"error": err.code, "version": err.version, "supported": list(SUPPORTED_VERSIONS)}, ensure_ascii=False, indent=2))
|
|
426
|
+
return 1
|
|
427
|
+
out = []
|
|
428
|
+
for c in source["claims"]:
|
|
429
|
+
if prop and c["property"] != prop and not c["property"].endswith("#" + prop):
|
|
430
|
+
continue
|
|
431
|
+
task = {"property": c["property"], "scope": scope, "requireReview": review}
|
|
432
|
+
if trust is not None:
|
|
433
|
+
task["trustedIssuers"] = trust
|
|
434
|
+
usable, reasons, value = evaluate(c, task, now, profiles, source_extensions=source["extensions"], known_extensions=known)
|
|
435
|
+
out.append({"claim": c["id"], "usable": usable, "reasons": reasons, "value": value, "scope": c["scope"], "valid_until": c["valid_until"]})
|
|
436
|
+
out.sort(key=lambda r: not r["usable"])
|
|
437
|
+
print(json.dumps(out, ensure_ascii=False, indent=2))
|
|
438
|
+
return 0
|
|
439
|
+
|
|
440
|
+
|
|
441
|
+
def main():
|
|
442
|
+
if len(sys.argv) >= 3 and sys.argv[1] == "conformance":
|
|
443
|
+
return run_conformance(sys.argv[2])
|
|
444
|
+
if len(sys.argv) >= 3 and sys.argv[1] == "ask":
|
|
445
|
+
return run_ask(sys.argv[2:])
|
|
446
|
+
print(__doc__)
|
|
447
|
+
return 2
|
|
448
|
+
|
|
449
|
+
|
|
450
|
+
if __name__ == "__main__":
|
|
451
|
+
sys.exit(main())
|