filip.models.ngsi_ld package

This package will contain models for FIWAREs NGSI-LD APIs

Submodules

filip.models.ngsi_ld.base module

pydantic model filip.models.ngsi_ld.base.GeoQuery[source]

Bases: BaseModel

GeoQuery used for Subscriptions, as described in NGSI-LD Spec section 5.2.13

Config:

  • populate_by_name: bool = True

Fields:
field coordinates: list | str [Required]

A JSON Array coherent with the geometry type as per IETF RFC 7946 [8]

field geometry: str [Required]

A valid GeoJSON [8] geometry, type excepting GeometryCollection

field geoproperty: str | None = None

Attribute Name as a short-hand string

field georel: str [Required]

A valid geo-relationship as defined by clause 4.10 (near, within, etc.)

filip.models.ngsi_ld.base.validate_ngsi_ld_query(q: str) → str[source]

Valid query string as described in NGSI-LD Spec section 5.2.12 :param q: query string

Returns:

filip.models.ngsi_ld.context module

NGSI LD models for context broker interaction

class filip.models.ngsi_ld.context.ActionTypeLD(value=<no_arg>, names=None, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: str, Enum

Options for queries

CREATE = 'create'
DELETE = 'delete'
UPDATE = 'update'
UPSERT = 'upsert'
pydantic model filip.models.ngsi_ld.context.ContextGeoProperty[source]

Bases: BaseModel

The model for a Geo property is represented by a JSON object with the following syntax:

The attribute value is a JSON object with two contents.

Example

{ “type”: “GeoProperty”, “value”: {

“type”: “Point”, “coordinates”: [

-3.80356167695194, 43.46296641666926

]

}

Config:

  • extra: str = allow

Fields:
field datasetId: str | None = None

It allows identifying a set or group of property values

Constraints:

  • min_length = 1

  • max_length = 256

field observedAt: str | None = None

Representing a timestamp for the incoming value of the property.

Constraints:

  • min_length = 1

  • max_length = 256

field type: str | None = 'GeoProperty'
field value: ContextGeoPropertyValue | Point | LineString | Polygon | MultiPoint | MultiPolygon | MultiLineString | None = None

the actual data

pydantic model filip.models.ngsi_ld.context.ContextGeoPropertyValue[source]

Bases: BaseModel

The value for a Geo property is represented by a JSON object with the following syntax:

A type with value “Point” and the coordinates with a list containing the coordinates as value

Example

“value”: {

“type”: “Point”, “coordinates”: [

-3.80356167695194, 43.46296641666926

]

}

}

Config:

  • extra: str = allow

Fields:
Validators:
field type: str | None = None
Validated by:
validator check_geoproperty_value  »  all fields[source]

Check if the value is a valid GeoProperty

pydantic model filip.models.ngsi_ld.context.ContextLDEntity[source]

Bases: ContextLDEntityKeyValues

Context LD entities, or simply entities, are the center of gravity in the FIWARE NGSI-LD information model. An entity represents a thing, i.e., any physical or logical object (e.g., a sensor, a person, a room, an issue in a ticketing system, etc.). Each entity has an entity id. Furthermore, the type system of FIWARE NGSI enables entities to have an entity type. Entity types are semantic types; they are intended to describe the type of thing represented by the entity. For example, a context entity #with id sensor-365 could have the type temperatureSensor.

Each entity is uniquely identified by its id.

The entity id is specified by the object’s id property, whose value is a string containing the entity id.

The entity type is specified by the object’s type property, whose value is a string containing the entity’s type name.

Entity attributes are specified by additional properties and relationships, whose names are the name of the attribute and whose representation is described in the “ContextProperty”/”ContextRelationship”-model. Obviously, id and type are not allowed to be used as attribute names.

Example

>>> data = {'id': 'MyId',
            'type': 'MyType',
            'my_attr': {'value': 20}}

>>> entity = ContextLDEntity(**data)
Config:

  • extra: str = allow

  • validate_default: bool = True

  • validate_assignment: bool = True

  • populate_by_name: bool = True

Fields:
Validators:
field context: str | List[str] | Dict | None = None (alias '@context')

The @context in JSON-LD is used to expand terms, provided as short hand strings, to concepts, specified as URIs, and vice versa, to compact URIs into terms The main implication of NGSI-LD API is that if the @context is a compound one, i.e. an @context which references multiple individual @context, served by resources behind different URIs, then a wrapper @context has to be created and hosted.

Validated by:
field createdAt: str | None = None

Representing a timestamp for the creation time of the property.

Constraints:

  • min_length = 1

  • max_length = 256

field modifiedAt: str | None = None

Representing a timestamp for the last modification of the property.

Constraints:

  • min_length = 1

  • max_length = 256

field observationSpace: ContextGeoProperty | None = None

The geospatial Property representing the geographic location that is being observed, e.g. by a sensor. For example, in the case of a camera, the location of the camera and the observationspace are different and can be disjoint.

field operationSpace: ContextGeoProperty | None = None

The geospatial Property representing the geographic location in which an Entity,e.g. an actuator is active. For example, a crane can have a certain operation space.

add_geo_properties(attrs: Dict[str, ContextGeoProperty] | List[NamedContextGeoProperty]) → None[source]

Add property to entity :param attrs:

Returns:

None

add_properties(attrs: Dict[str, ContextProperty] | List[NamedContextProperty]) → None[source]

Add property to entity :param attrs:

Returns:

None

add_relationships(relationships: Dict[str, ContextRelationship] | List[NamedContextRelationship]) → None[source]

Add relationship to entity :param relationships:

Returns:

None

delete_properties(props: Dict[str, ContextProperty] | List[NamedContextProperty] | List[str])[source]

Delete the given properties from the entity

Parameters:

props – can be given in multiple forms 1) Dict: {“<property_name>”: ContextProperty, …} 2) List: [NamedContextProperty, …] 3) List: [“<property_name>”, …]

Returns:

delete_relationships(relationships: List[str])[source]

Delete the given relationships from the entity

Parameters:

relationships – List of relationship names

Returns:

get_context()[source]
Parameters:

response_format –

Returns: context of the entity as list

classmethod get_model_fields_set()[source]

Get all names and aliases of the model fields.

get_properties(response_format: str | PropertyFormat = PropertyFormat.LIST) → List[NamedContextProperty] | Dict[str, ContextProperty][source]

Get all properties of the entity. :param response_format:

Returns:

get_relationships(response_format: str | PropertyFormat = PropertyFormat.LIST) → List[NamedContextRelationship] | Dict[str, ContextRelationship][source]

Get all relationships of the context entity

Parameters:

response_format –

Returns:

model_dump(*args, by_alias: bool = True, **kwargs)[source]

Usage docs: https://docs.pydantic.dev/2.6/concepts/serialization/#modelmodel_dump

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

Parameters:

  • mode – The mode in which to_python should run. If mode is ‘json’, the output will only contain JSON serializable types. If mode is ‘python’, the output may contain non-JSON-serializable Python objects.

  • include – A list of fields to include in the output.

  • exclude – A list of fields to exclude from the output.

  • by_alias – Whether to use the field’s alias in the dictionary key if defined.

  • exclude_unset – Whether to exclude fields that have not been explicitly set.

  • exclude_defaults – Whether to exclude fields that are set to their default value.

  • exclude_none – Whether to exclude fields that have a value of None.

  • round_trip – If True, dumped values should be valid as input for non-idempotent types such as Json[T].

  • warnings – Whether to log warnings when invalid fields are encountered.

Returns:

A dictionary representation of the model.

validator return_context  »  context[source]
pydantic model filip.models.ngsi_ld.context.ContextLDEntityKeyValues[source]

Bases: BaseModel

Base Model for an entity is represented by a JSON object with the following syntax.

The entity id is specified by the object’s id property, whose value is a string containing the entity id.

The entity type is specified by the object’s type property, whose value is a string containing the entity’s type name.

Config:

  • extra: str = allow

  • validate_default: bool = True

  • validate_assignment: bool = True

Fields:
field id: str [Required]

Id of an entity in an NGSI context broker. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.the id should be structured according to the urn naming scheme.

Constraints:

  • min_length = 1

  • max_length = 256

field type: str [Required]

Id of an entity in an NGSI context broker. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

pydantic model filip.models.ngsi_ld.context.ContextProperty[source]

Bases: BaseModel

The model for a property is represented by a JSON object with the following syntax:

The attribute value is specified by the value, whose value can be any data type. This does not need to be specified further.

The NGSI type of the attribute is fixed and does not need to be specified. .. rubric:: Example

>>> data = {"value": <...>}

>>> attr = ContextProperty(**data)
Config:

  • extra: str = allow

Fields:
Validators:
field UnitCode: str | None = None

Representing the unit of the value. Should be part of the defined units by the UN/ECE Recommendation No. 21https://unece.org/fileadmin/DAM/cefact/recommendations/rec20/rec20_rev3_Annex2e.pdf

Constraints:

  • min_length = 1

  • max_length = 256

field createdAt: str | None = None

Representing a timestamp for the creation time of the property.

Constraints:

  • min_length = 1

  • max_length = 256

field datasetId: str | None = None

It allows identifying a set or group of property values

Constraints:

  • min_length = 1

  • max_length = 256

field modifiedAt: str | None = None

Representing a timestamp for the last modification of the property.

Constraints:

  • min_length = 1

  • max_length = 256

field observedAt: str | None = None

Representing a timestamp for the incoming value of the property.

Constraints:

  • min_length = 1

  • max_length = 256

field type: str | None = 'Property'
Validated by:
field value: float | int | bool | str | List | Dict[str, Any] | List[float | int | bool | str | List | Dict[str, Any]] | None = None

the actual data

validator check_property_type  »  type[source]

Force property type to be “Property” :param value: value field

Returns:

value

classmethod get_model_fields_set()[source]

Get all names and aliases of the model fields.

pydantic model filip.models.ngsi_ld.context.ContextRelationship[source]

Bases: BaseModel

The model for a relationship is represented by a JSON object with the following syntax:

The attribute value is specified by the object, whose value can be a reference to another context entity. This should be specified as the URN. The existence of this entity is not assumed.

The NGSI type of the attribute is fixed and does not need to be specified.

Example

>>> data = {"object": <...>}

>>> attr = ContextRelationship(**data)
Config:

  • extra: str = allow

Fields:
Validators:
field datasetId: str | None = None

It allows identifying a set or group of property values

Constraints:

  • min_length = 1

  • max_length = 256

field object: float | int | bool | str | List | Dict[str, Any] | List[float | int | bool | str | List | Dict[str, Any]] | None = None

the actual object id

field observedAt: str | None = None

Representing a timestamp for the incoming value of the property.

Constraints:

  • min_length = 1

  • max_length = 256

field type: str | None = 'Relationship'
Validated by:
validator check_relationship_type  »  type[source]

Force property type to be “Relationship” :param value: value field

Returns:

value

class filip.models.ngsi_ld.context.DataTypeLD(value=<no_arg>, names=None, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: str, Enum

In NGSI-LD the data types on context entities are only divided into properties and relationships.

GEOPROPERTY = 'GeoProperty'
PROPERTY = 'Property'
RELATIONSHIP = 'Relationship'
pydantic model filip.models.ngsi_ld.context.NamedContextGeoProperty[source]

Bases: ContextGeoProperty

Context GeoProperties are geo properties of context entities. For example, the coordinates of a building .

In the NGSI-LD data model, properties have a name, the type “Geoproperty” and a value.

Config:

  • extra: str = allow

Fields:
field name: str [Required]

The property name describes what kind of property the attribute value represents of the entity, for example current_speed. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

pydantic model filip.models.ngsi_ld.context.NamedContextProperty[source]

Bases: ContextProperty

Context properties are properties of context entities. For example, the current speed of a car could be modeled as the current_speed property of the car-104 entity.

In the NGSI-LD data model, properties have a name, the type “property” and a value.

Config:

  • extra: str = allow

Fields:
Validators:

field name: str [Required]

The property name describes what kind of property the attribute value represents of the entity, for example current_speed. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

pydantic model filip.models.ngsi_ld.context.NamedContextRelationship[source]

Bases: ContextRelationship

Context Relationship are relations of context entities to each other. For example, the current_speed of the entity car-104 could be modeled. The location could be modeled as located_in the entity Room-001.

In the NGSI-LD data model, relationships have a name, the type “relationship” and an object.

Config:

  • extra: str = allow

Fields:
Validators:

field name: str [Required]

The attribute name describes what kind of property the attribute value represents of the entity, for example current_speed. Allowed characters are the ones in the plain ASCII set, except the following ones: control characters, whitespace, &, ?, / and #.

Constraints:

  • min_length = 1

  • max_length = 256

class filip.models.ngsi_ld.context.PropertyFormat(value=<no_arg>, names=None, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: str, Enum

Format to decide if properties of ContextEntity class are returned as List of NamedContextAttributes or as Dict of ContextAttributes.

DICT = 'dict'
LIST = 'list'
pydantic model filip.models.ngsi_ld.context.UpdateLD[source]

Bases: BaseModel

Model for update action

Fields:
field entities: List[ContextLDEntity | ContextLDEntityKeyValues] [Required]

an array of entities, each entity specified using the JSON entity representation format

filip.models.ngsi_ld.subscriptions module

pydantic model filip.models.ngsi_ld.subscriptions.Endpoint[source]

Bases: BaseModel

This datatype represents the parameters that are required in order to define an endpoint for notifications. This can include the endpoint’s URI, a generic{key, value} array, named receiverInfo, which contains, in a generalized form, whatever extra information the broker shall convey to the receiver in order for the broker to successfully communicate with receiver (e.g Authorization material), or for the receiver to correctly interpret the received content (e.g. the Link URL to fetch an @context).

Additionally, it can include another generic{key, value} array, named notifierInfo, which contains the configuration that the broker needs to know in order to correctly set up the communication channel towards the receiver

Example of “receiverInfo”
“receiverInfo”: [
{

“key”: “H1”, “value”: “123”

}, {

“key”: “H2”, “value”: “456”

}

]

Example of “notifierInfo”
“notifierInfo”: [
{

“key”: “MQTT-Version”, “value”: “mqtt5.0”

}

]

Config:

  • populate_by_name: bool = True

Fields:
Validators:
field accept: str | None = None

MIME type for the notification payload body (application/json, application/ld+json, application/geo+json)

field notifierInfo: List[KeyValuePair] | None = None

Generic {key, value} array to set up the communication channel

Validated by:
field receiverInfo: List[KeyValuePair] | None = None

Generic {key, value} array to convey optional information to the receiver

field uri: Url [Required]

Dereferenceable URI

Validated by:
validator check_notifier_info  »  notifierInfo[source]
validator check_uri  »  uri[source]
pydantic model filip.models.ngsi_ld.subscriptions.EntityInfo[source]

Bases: BaseModel

In v1.3.1 it is specified as EntityInfo In v1.6.1 it is specified in a new data type, namely EntitySelector

Config:

  • populate_by_name: bool = True

Fields:
field id: Url | None = None

Entity identifier (valid URI)

field idPattern: str | None = None

Regular expression as per IEEE POSIX 1003.2™ [11]

field type: str [Required]

Fully Qualified Name of an Entity Type or the Entity Type Name as a short-hand string. See clause 4.6.2

pydantic model filip.models.ngsi_ld.subscriptions.KeyValuePair[source]

Bases: BaseModel

Fields:
field key: str [Required]
field value: str [Required]
pydantic model filip.models.ngsi_ld.subscriptions.NotificationParams[source]

Bases: BaseModel

NGSI-LD Notification model. It contains the parameters that allow to convey the details of a notification, as described in NGSI-LD Spec section 5.2.14

Config:

  • populate_by_name: bool = True

Fields:
field attributes: List[str] | None = None

Entity Attribute Names (Properties or Relationships) to be included in the notification payload body. If undefined, it will mean all Attributes

field endpoint: Endpoint [Required]

Notification endpoint details

field format: str | None = 'normalized'

Conveys the representation format of the entities delivered at notification time. By default, it will be in normalized format

field lastFailure: str | None = None

Timestamp corresponding to the instant when the last notification resulting in failure was sent. Provided by the system when querying the details of a subscription

field lastNotification: str | None = None

Timestamp corresponding to the instant when the last notification was sent. Provided by the system when querying the details of a subscription

field lastSuccess: str | None = None

Timestamp corresponding to the instant when the last successful notification was sent. Provided by the system when querying the details of a subscription

field status: Literal['ok', 'failed'] = 'ok'

Status of the Notification. It shall be ‘ok’ if the last attempt to notify the subscriber succeeded. It shall be ‘failed’ if the last attempt to notify the subscriber failed

field timesSent: int | None = None

Number of times that the notification was sent. Provided by the system when querying the details of a subscription

pydantic model filip.models.ngsi_ld.subscriptions.SubscriptionLD[source]

Bases: BaseModel

Context Subscription model according to NGSI-LD Spec section 5.2.12

Config:

  • populate_by_name: bool = True

Fields:
Validators:
field csf: str | None = None

Context source filter

field description: str | None = None

Subscription description

field entities: List[EntityInfo] | None = None

Entities subscribed

field expiresAt: str | None = None

Expiration date for the subscription

field geoQ: GeoQuery | None = None

Geoquery met by subscribed entities to trigger the notification

field id: str | None = None

Subscription identifier (JSON-LD @id)

field isActive: bool = True

Indicates if the Subscription is under operation (True) or paused (False)

field lang: str | None = None

Language filter applied to the query

field notification: NotificationParams [Required]

Notification details

field notificationTrigger: List[str] | None = None

Notification triggers

field q: str | None = None

Query met by subscribed entities to trigger the notification

Validated by:
field subscriptionName: str | None = None

A (short) name given to this Subscription

field temporalQ: TemporalQuery | None = None

Temporal Query

field throttling: int | None = None

Minimal period of time in seconds between two consecutive notifications

field timeInterval: int | None = None

Time interval in seconds

field type: str = 'Subscription'

JSON-LD @type

field watchedAttributes: List[str] | None = None

Watched Attributes (Properties or Relationships)

validator check_q  »  q[source]
pydantic model filip.models.ngsi_ld.subscriptions.TemporalQuery[source]

Bases: BaseModel

Temporal query according to NGSI-LD Spec section 5.2.21

timerel:

Temporal relationship, one of “before”, “after” and “between”. “before”: before the time specified by timeAt. “after”: after the time specified by timeAt. “between”: after the time specified by timeAt and before the time specified by

endtimeAt

timeAt:

A DateTime object following ISO 8061, e.g. 2007-12-24T18:21Z

endTimeAt (optional):

A DateTime object following ISO 8061, e.g. 2007-12-24T18:21Z Only required when timerel=”between”

timeproperty: str

Representing a Propertyname of the Property that contains the temporal data that will be used to resolve the temporal query. If not specified, the default is “observedAt”

Config:

  • populate_by_name: bool = True

Fields:
Validators:
field endTimeAt: str | None = None

String representing the endTimeAt parameter as defined by clause 4.11. It shall be a DateTime. Cardinality shall be 1 if timerel is equal to ‘between’

Validated by:
field timeAt: str [Required]

String representing the timeAt parameter as defined by clause 4.11. It shall be a DateTime

Validated by:
field timeproperty: str | None = None

String representing a Property name. The name of the Property that contains the temporal data that will be used to resolve the temporal query. If not specified,

Validated by:
field timerel: Literal['before', 'after', 'between'] [Required]

String representing the temporal relationship as defined by clause 4.11 (Allowed values: ‘before’, ‘after’, and ‘between’)

Validated by:
validator check_passwords_match  »  all fields[source]
validator check_uri  »  endTimeAt, timeAt[source]