Basic Usage
Getting Started
For the most basic usage, see the following example.
from pydantic_jsonld.compact import BaseModel, Value
# Define a model
class PersonModel(BaseModel):
name: Value[str]
age: Value[int]
# Build an instance from JSON-LD data
data = {
"@context": {"@vocab": "http://www.example.org/"},
"name": "Alice",
"age": 30,
}
model = PersonModel.model_validate(data)
# Access via model properties
assert model.name.value == "Alice"
assert model.age.value == 30
# Recover the original data
dumped = model.model_dump(by_alias=True, exclude_none=True)
assert dumped == data
from pydantic_jsonld.compact import BaseModel, Value
# Define a model
class AreaModel(BaseModel):
height: Value[float]
length: Value[float]
# Build an instance from JSON-LD data
data = {
"@context": {"@vocab": "http://www.example.org/"},
"height": 20.0,
"length": 10.0,
}
model = AreaModel.model_validate(data)
# Access via model properties
assert model.height.value == 20.0
assert model.length.value == 10.0
# Recover the original data
dumped = model.model_dump(by_alias=True, exclude_none=True)
assert dumped == data
from pydantic_jsonld.compact import BaseModel, Value
# Define a model
class ProductModel(BaseModel):
name: Value[str]
price: Value[float]
in_stock: Value[bool]
# Build an instance from JSON-LD data
data = {
"@context": {"@vocab": "http://www.example.org/"},
"name": "Notebook",
"price": 12.99,
"inStock": False,
}
model = ProductModel.model_validate(data)
# Access via model properties
assert model.name.value == "Notebook"
assert model.price.value == 12.99
assert model.in_stock.value is False
# Recover the original data
dumped = model.model_dump(by_alias=True, exclude_none=True)
assert dumped == data
Complex Values
Additional information provided in value objects is captured as well.
from pydantic_jsonld.compact import BaseModel, Value
class PersonModel(BaseModel):
name: Value[str]
age: Value[int]
data = {
"@context": {"@vocab": "http://www.example.org/"},
"name": {
"@value": "Alice",
"@language": "en",
},
"age": {
"@value": 30,
"@type": "http://www.w3.org/2001/XMLSchema#integer",
},
}
model = PersonModel.model_validate(data)
assert model.name.value == "Alice"
assert model.name.language == "en"
assert model.age.value == 30
assert model.age.type == "http://www.w3.org/2001/XMLSchema#integer"
dumped = model.model_dump(by_alias=True, exclude_none=True)
assert dumped == data
from pydantic_jsonld.compact import BaseModel, Value
class AreaModel(BaseModel):
height: Value[float]
length: Value[float]
data = {
"@context": {"@vocab": "http://www.example.org/"},
"height": {
"@value": 20.0,
"@type": "http://www.w3.org/2001/XMLSchema#double",
},
"length": {
"@value": 10.0,
"@type": "http://www.w3.org/2001/XMLSchema#double",
},
}
model = AreaModel.model_validate(data)
assert model.height.value == 20.0
assert model.height.type == "http://www.w3.org/2001/XMLSchema#double"
assert model.length.value == 10.0
assert model.length.type == "http://www.w3.org/2001/XMLSchema#double"
dumped = model.model_dump(by_alias=True, exclude_none=True)
assert dumped == data
from pydantic_jsonld.compact import BaseModel, Value
class ProductModel(BaseModel):
name: Value[str]
price: Value[float]
in_stock: Value[bool]
data = {
"@context": {"@vocab": "http://www.example.org/"},
"name": {
"@value": "Notebook",
"@language": "en",
},
"price": {
"@value": 12.99,
"@type": "http://www.w3.org/2001/XMLSchema#decimal",
},
"inStock": {
"@value": False,
"@type": "http://www.w3.org/2001/XMLSchema#boolean",
},
}
model = ProductModel.model_validate(data)
assert model.name.value == "Notebook"
assert model.name.language == "en"
assert model.price.value == 12.99
assert model.price.type == "http://www.w3.org/2001/XMLSchema#decimal"
assert model.in_stock.value is False
assert model.in_stock.type == "http://www.w3.org/2001/XMLSchema#boolean"
dumped = model.model_dump(by_alias=True, exclude_none=True)
assert dumped == data
Value Keywords
The keywords captured are @type, @language, and @direction.
Plain values
Conversely, if you know that some property will always have plain scalar values, you may also simplify the property's class declaration.
from pydantic_jsonld.compact import BaseModel
class PersonModel(BaseModel):
name: str
age: int
data = {
"@context": {"@vocab": "http://www.example.org/"},
"name": "Alice",
"age": 30,
}
model = PersonModel.model_validate(data)
assert model.name == "Alice"
assert model.age == 30
dumped = model.model_dump(by_alias=True, exclude_none=True)
assert dumped == data
from pydantic_jsonld.compact import BaseModel
class AreaModel(BaseModel):
height: float
length: float
data = {
"@context": {"@vocab": "http://www.example.org/"},
"height": 20.0,
"length": 10.0,
}
model = AreaModel.model_validate(data)
assert model.height == 20.0
assert model.length == 10.0
dumped = model.model_dump(by_alias=True, exclude_none=True)
assert dumped == data
from pydantic_jsonld.compact import BaseModel
class ProductModel(BaseModel):
name: str
price: float
in_stock: bool
data = {
"@context": {"@vocab": "http://www.example.org/"},
"name": "Notebook",
"price": 12.99,
"inStock": False,
}
model = ProductModel.model_validate(data)
assert model.name == "Notebook"
assert model.price == 12.99
assert model.in_stock is False
dumped = model.model_dump(by_alias=True, exclude_none=True)
assert dumped == data
Validation Failure
If a particular data entry happens to have a value object which is not a plain scalar value, the validation will fail for that instance.
Optional Properties
Optional properties can be defined in the same way as in regular pydantic.
from pydantic_jsonld.compact import BaseModel, Value
class PersonModel(BaseModel):
name: Value[str]
age: Value[int] | None = None
data = {
"@context": {"@vocab": "http://www.example.org/"},
"name": "Alice",
}
model = PersonModel.model_validate(data)
assert model.name.value == "Alice"
assert model.age is None
dumped = model.model_dump(by_alias=True, exclude_none=True)
assert dumped == data
from pydantic_jsonld.compact import BaseModel, Value
class AreaModel(BaseModel):
height: Value[float]
length: Value[float] | None = None
data = {
"@context": {"@vocab": "http://www.example.org/"},
"height": 20.0,
}
model = AreaModel.model_validate(data)
assert model.height.value == 20.0
assert model.length is None
dumped = model.model_dump(by_alias=True, exclude_none=True)
assert dumped == data
from pydantic_jsonld.compact import BaseModel, Value
class ProductModel(BaseModel):
name: Value[str]
price: Value[float]
in_stock: Value[bool] | None = None
data = {
"@context": {"@vocab": "http://www.example.org/"},
"name": "Notebook",
"price": 12.99,
}
model = ProductModel.model_validate(data)
assert model.name.value == "Notebook"
assert model.price.value == 12.99
assert model.in_stock is None
dumped = model.model_dump(by_alias=True, exclude_none=True)
assert dumped == data