Reviewing and fixing issues regarding schemas, headers and parameters sections... (322364d7) · Commits · CIM - Context Information Management / NGSI-LD OpenAPI

ngsi-ld-api.yaml

+114 −55

Original line number	Diff line number	Diff line
		@@ -190,7 +190,6 @@ paths:
		# Query params
		- $ref: '#/components/parameters/Query.attrs'
		- $ref: '#/components/parameters/Query.geometryProperty'
		# REVIEW Options entities
		- $ref: '#/components/parameters/Query.lang'
		- $ref: '#/components/parameters/Query.options.entities'
		# Local Query param
		@@ -2643,7 +2642,7 @@ components:
		type: string
		NGSILD-Results-Count:
		description: \|
		6.3.13 Counting number of results
		6.3.13 Counting number of results. The total number of matching results (e.g. number of Entities) is returned.
		schema:
		type: integer
		NGSILD-Tenant:
		@@ -2681,14 +2680,6 @@ components:
		schema:
		type: string
		format: uri
		Headers.ngsildCount:
		name: NGSILD-Results-Count
		in: header
		description: \|
		6.3.13 Counting number of results. The total number of matching results (e.g. number of Entities) is returned.
		explode: true
		schema:
		type: integer
		Headers.ngsildTenant:
		name: NGSILD-Tenant
		in: header
		@@ -2706,6 +2697,7 @@ components:
		given that the latter is part of the JSON-LD @context provided.
		schema:
		type: string
		format: uri
		required: true
		Path.contextId:
		name: contextId
		@@ -2715,6 +2707,7 @@ components:
		this can also be the original URL the Broker downloaded the @context from.
		schema:
		type: string
		format: uri
		required: true
		Path.entityId:
		name: entityId
		@@ -2757,6 +2750,7 @@ components:
		given that the latter is part of the JSON-LD @context provided.
		schema:
		type: string
		format: uri
		required: true
		Query.aggrMethods:
		name: aggrMethods
		@@ -2822,6 +2816,7 @@ components:
		- $ref: '#/components/schemas/Geometry.position'
		- $ref: '#/components/schemas/Geometry.positionArray'
		- $ref: '#/components/schemas/Geometry.lineString'
		- $ref: '#/components/schemas/Geometry.linearRing'
		- $ref: '#/components/schemas/Geometry.polygon'
		required: false
		Query.count:
		@@ -2915,6 +2910,10 @@ components:
		name: geometryProperty
		in: query
		description: \|
		4.5.16.1 Top-level "geometry" field selection algorithm.
		A parameter of the request (named "geometryProperty") may be used to indicate the name of the GeoProperty to be selected.
		If this parameter is not present, then the default name of "location" shall be used.

		In the case of GeoJSON Entity representation, this parameter indicates which GeoProperty to use
		for the toplevel geometry field.
		style: form
		@@ -3046,7 +3045,6 @@ components:
		type: string
		format: date-time
		required: false
		# REVIEW
		Query.options.entities:
		name: options
		in: query
		@@ -3279,7 +3277,7 @@ components:
		- $ref: '#/components/schemas/Subscription'
		- required:
		- type
		- entities
		- notification
		application/json+ld:
		schema:
		allOf:
		@@ -3290,6 +3288,7 @@ components:
		$ref: '#/components/schemas/LdContext'
		- required:
		- type
		- notification
		- '@context'
		SubscriptionFragment:
		content:
		@@ -3313,7 +3312,9 @@ components:
		# Beginning of Options parameters
		#
		options.noOverwrite:
		description: Indicates that no attribute overwrite shall be performed.
		description: \|
		6.16.3 For POST method associated to the operation "Batch Entity Update", the "noOvevwrite"
		options query parameter indicates that no attribute overwrite shall be performed.
		type: string
		enum:
		- noOverwrite
		@@ -3378,6 +3379,7 @@ components:
		enum:
		- replace
		- update
		default: replace
		#
		# End of Options parameters
		###
		@@ -3389,19 +3391,23 @@ components:
		description: \|
		Is defined as the temporal Property at which the Entity, Property or
		Relationship was entered into an NGSI-LD system.

		Entity creation timestamp. See clause 4.8.
		type: string
		format: date-time
		ModifiedAt:
		description: \|
		Is defined as the temporal Property at which the Entity, Property or Relationship
		was last modified in an NGSI-LD system, e.g. in order to correct a previously entered incorrect value.

		Entity last modification timestamp. See clause 4.8.
		type: string
		format: date-time
		DeletedAt:
		description: \|
		Is defined as the temporal Property at which the Entity, Property or Relationship was deleted from an NGSI-LD system.

		Entity deletion timestamp. See clause 4.8 It is only used in notifications reporting deletions and in the
		Entity deletion timestamp. See clause 4.8. It is only used in notifications reporting deletions and in the
		Temporal Representation of Entities (clause 4.5.6), Properties (clause 4.5.7), Relationships (clause 4.5.8)
		and LanguageProperties (clause 5.2.32).
		type: string
		@@ -3415,7 +3421,6 @@ components:
		#
		# End of 4.8 Temporal Properties
		###

		Attribute:
		description: \|
		5.2.28 This type represents the data needed to define the attribute information.
		@@ -3487,7 +3492,7 @@ components:
		- attributeList
		BatchEntityError:
		description: \|
		5.2.17 represents an error raised (associated to a particular Entity) during
		5.2.17 This datatype represents an error raised (associated to a particular Entity) during
		the execution of a batch or distributed operation.
		type: object
		properties:
		@@ -3510,7 +3515,7 @@ components:
		- error
		BatchOperationResult:
		description: \|
		5.2.16 represents the result of a batch operation.
		5.2.16 The datatype represents the result of a batch operation.
		type: object
		properties:
		success:
		@@ -3595,7 +3600,7 @@ components:
		- triggerReason
		CsourceRegistration:
		description: \|
		5.2.9 represents the data needed to register a new Context Source.
		5.2.9 This type represents the data needed to register a new Context Source.
		type: object
		properties:
		id:
		@@ -3658,8 +3663,16 @@ components:
		Location for which the Context Source may be able to provide information.
		$ref: '#/components/schemas/Geometry'
		observationSpace:
		description: \|
		Geographic location that includes the observation spaces of all entities as specified by their
		respective observationSpace GeoProperty for which the Context Source may be able to provide
		information.
		$ref: '#/components/schemas/Geometry'
		operationSpace:
		description: \|
		Geographic location that includes the operation spaces of all entities as specified by their
		respective operationSpace GeoProperty for which the Context Source may be able to provide
		information.
		$ref: '#/components/schemas/Geometry'
		expiresAt:
		description: \|
		@@ -3697,6 +3710,7 @@ components:
		- exclusive
		- redirect
		- auxiliary
		default: inclusive
		operations:
		description: \|
		The definition limited subset of API operations supported by the registered Context Source.
		@@ -3766,7 +3780,7 @@ components:
		$ref: '#/components/schemas/AnyValue'
		DateTimeValue:
		description: \|
		Date representation as mandated by C.6 "Date Representation"
		Date representation as mandated by C.6 "Date Representation".
		type: object
		properties:
		'@type':
		@@ -3782,7 +3796,7 @@ components:
		- '@value'
		Endpoint:
		description: \|
		5.2.15 represents the parameters that are required in order to define an endpoint for notifications.
		5.2.15 This datatype represents the parameters that are required in order to define an endpoint for notifications.
		type: object
		properties:
		uri:
		@@ -3802,15 +3816,17 @@ components:
		timeout:
		description: \|
		Maximum period of time in milliseconds which may elapse before a notification is assumed to have failed.
		The NGSI-LD system can override this value. This only applies if the binding
		protocol always returns a response.
		The NGSI-LD system can override this value. This only applies if the binding protocol always returns a
		response.
		type: number
		minimum: 1
		cooldown:
		description: \|
		Once a failure has occurred, minimum period of time in milliseconds which shall elapse before
		attempting to make a subsequent notification to the same endpoint after failure.
		If requests are received before the cooldown period has expired, no notification is sent.
		type: number
		minimum: 1
		receiverInfo:
		description: \|
		Generic {key, value} array to convey optional information to the receiver.
		@@ -3827,7 +3843,7 @@ components:
		- uri
		Entity:
		description: \|
		NGSI-LD Entity (see 5.4).
		5.2.4 NGSI-LD Entity.
		type: object
		properties:
		id:
		@@ -3856,8 +3872,12 @@ components:
		Default geospatial Property of an entity. See clause 4.7.
		$ref: '#/components/schemas/GeoProperty'
		observationSpace:
		description: \|
		See clause 4.7.
		$ref: '#/components/schemas/GeoProperty'
		operationSpace:
		description: \|
		See clause 4.7.
		$ref: '#/components/schemas/GeoProperty'
		# Clause 5.2.2 Common members. System-generated
		createdAt:
		@@ -3884,8 +3904,8 @@ components:
		$ref: '#/components/schemas/Relationship'
		EntityInfo:
		description: \|
		5.2.8 represents what Entities, Entity Types or group of Entity ids
		(as a regular expression pattern mandated by IEEE 1003.2TM [11]) can be provided (by Context Sources).
		5.2.8 This type represents what Entities, Entity Types or group of Entity ids
		(as a regular expression pattern mandated by IEEE 1003.2TM) can be provided (by Context Sources).
		type: object
		properties:
		id:
		@@ -3911,7 +3931,7 @@ components:
		EntitySelector:
		description: \|
		5.2.33 This type selects which entity or group of entities are queried or subscribed to by Context Consumers.
		`id` takes precedence over `idPattern`.
		The `id` takes precedence over `idPattern`.
		type: object
		properties:
		id:
		@@ -3923,6 +3943,7 @@ components:
		description: \|
		A regular expression which denotes a pattern that shall be matched by the provided or subscribed Entities.
		type: string
		format: pattern
		type:
		description: \|
		Selector of Entity Type(s).
		@@ -3938,13 +3959,38 @@ components:
		the EntityTemporal by using the "Simplified Temporal Representation of an Entity",
		as defined in clause 4.5.9.
		properties:
		id:
		description: \|
		Entity id.
		type: string
		format: uri
		type:
		description: \|
		Entity Type(s). Both short hand string(s) (type name) or URI(s) are allowed.
		oneOf:
		- type: string
		- type: array
		items:
		type: string
		scope:
		description: \|
		Scope.
		oneOf:
		- type: string
		- type: array
		items:
		type: string
		location:
		description: \|
		Default geospatial Property of an entity. See clause 4.7.
		$ref: '#/components/schemas/GeoProperty'
		observationSpace:
		description: \|
		See clause 4.7.
		$ref: '#/components/schemas/GeoProperty'
		operationSpace:
		description: \|
		See clause 4.7.
		$ref: '#/components/schemas/GeoProperty'
		# Clause 5.2.2 Common members. System-generated
		createdAt:
		@@ -4096,7 +4142,7 @@ components:
		'@context':
		description: \|
		JSON-LD @context. This field is only present if requested in the payload by
		the HTTP Prefer Header (IETF RFC 724).
		the HTTP Prefer Header (IETF RFC 7240).
		$ref: '#/components/schemas/LdContext'
		required:
		- id
		@@ -4124,7 +4170,7 @@ components:
		'@context':
		description: \|
		JSON-LD @context. This field is only present if requested in the payload
		by the HTTP Prefer Header (IETF RFC 724).
		by the HTTP Prefer Header (IETF RFC 7240).
		$ref: '#/components/schemas/LdContext'
		required:
		- type
		@@ -4171,7 +4217,7 @@ components:
		A single position.
		type: array
		minItems: 2
		maxItems: 2
		maxItems: 3
		items:
		type: number
		additionalProperties: false
		@@ -4189,7 +4235,7 @@ components:
		- minItems: 2
		Geometry.linearRing:
		description: \|
		An array of four positions where the first equals the last.
		An array of four positions where the first equals the last (i.e., a closed LineString).
		allOf:
		- $ref: '#/components/schemas/Geometry.positionArray'
		- minItems: 4
		@@ -4259,7 +4305,7 @@ components:
		$ref: '#/components/schemas/Geometry.lineString'
		Geometry:
		description: \|
		A valid GeoJSON geometry object.
		A valid GeoJSON geometry object (as mandated by RFC7946).
		oneOf:
		- $ref: '#/components/schemas/Geometry.Point'
		- $ref: '#/components/schemas/Geometry.MultiPoint'
		@@ -4283,8 +4329,12 @@ components:
		- GeoProperty
		default: GeoProperty
		value:
		description: \|
		Geolocation encoded as GeoJSON. As mandated by clause 4.7.
		$ref: '#/components/schemas/Geometry'
		observedAt:
		description: \|
		Timestamp. See clause 4.8.
		$ref: '#/components/schemas/ObservedAt'
		datasetId:
		description: \|
		@@ -4323,9 +4373,10 @@ components:
		$ref: '#/components/schemas/Relationship'
		GeoQuery:
		description: \|
		5.2.13 represents a geoquery used for Subscriptions.
		5.2.13 This datatype represents a geoquery used for Subscriptions.
		type: object
		properties:
		# Could be of Geometry schema type
		geometry:
		description: \|
		Type of the reference geometry.
		@@ -4386,6 +4437,8 @@ components:
		String Property Values defined in multiple natural languages.
		type: object
		observedAt:
		description: \|
		Timestamp. See clause 4.8.
		$ref: '#/components/schemas/ObservedAt'
		datasetId:
		description: \|
		@@ -4414,7 +4467,8 @@ components:
		readOnly: true
		previousLanguageMap:
		description: \|
		Previous Language Property languageMap. Only used in notifications.
		Previous Language Property languageMap. Only used in notifications, if the showChanges
		option is explicitly requested.
		type: object
		readOnly: true
		additionalProperties:
		@@ -4446,7 +4500,7 @@ components:
		- type: object
		NotUpdatedDetails:
		description: \|
		5.2.19 represents additional information provided by an implementation
		5.2.19 This datatype represents additional information provided by an implementation
		when an Attribute update did not happen.
		type: object
		properties:
		@@ -4516,7 +4570,7 @@ components:
		- data
		NotificationParams:
		description: \|
		5.2.14 represents the parameters that allow to convey the details of a notification.
		5.2.14 This datatype represents the parameters that allow to convey the details of a notification.
		type: object
		properties:
		attributes:
		@@ -4532,6 +4586,7 @@ components:
		If true, the system generated attributes createdAt and modifiedAt are included in
		the response payload body, in the case of a deletion also deletedAt.
		type: boolean
		default: false
		format:
		description: \|
		Conveys the representation format of the entities delivered at notification time.
		@@ -4548,6 +4603,7 @@ components:
		This requires that it exists, i.e. in case of modifications and deletions,
		but not in the case of creations. showChanges cannot be true in case format is "keyValues".
		type: boolean
		default: false
		endpoint:
		description: \|
		Notification endpoint details.
		@@ -4565,13 +4621,13 @@ components:
		Number of times that the notification has been sent. Provided by the system when
		querying the details of a subscription.
		type: number
		minimum: 0
		minimum: 1
		timesFailed:
		description: \|
		Number of times an unsuccessful response (or timeout) has been received when deliverying the notification.
		Provided by the system when querying the details of a subscription.
		type: number
		minimum: 0
		minimum: 1
		lastNotification:
		description: \|
		Timestamp corresponding to the instant when the last notification has been sent.
		@@ -4599,17 +4655,17 @@ components:
		ProblemDetails:
		description: \|
		The definition of the general "ProblemDetails" data structure from
		IETF RFC 7807 [19] is reproduced inthis structure. Compared to the
		general framework defined in IETF RFC 7807 [19], the "status" and
		IETF RFC 7807 is reproduced inthis structure. Compared to the
		general framework defined in IETF RFC 7807, the "status" and
		"detail" attributes are mandated to be included by the present document,
		to ensure that the response contains additional textual information about
		an error. IETF RFC 7807 [19] foresees extensibility of the
		an error. IETF RFC 7807 foresees extensibility of the
		"ProblemDetails" type. It is possible that particular APIs in the present
		document, or particular implementations, define extensions to define
		additional attributes that provide more information about the error.
		The description column only provides some explanation of the meaning to
		Facilitate understanding of the design. For a full description, see
		IETF RFC 7807 [19].
		IETF RFC 7807.
		type: object
		required:
		- status
		@@ -4617,7 +4673,7 @@ components:
		properties:
		type:
		description: \|
		A URI reference according to IETF RFC 3986 [5] that identifies the
		A URI reference according to IETF RFC 3986 that identifies the
		problem type. It is encouraged that the URI provides human-readable
		documentation for the problem (e.g. using HTML) when dereferenced.
		When this member is not present, its value is assumed to be
		@@ -4674,11 +4730,9 @@ components:
		- $ref: '#/components/schemas/DateTimeValue'
		- $ref: '#/components/schemas/AnyValue'
		observedAt:
		$ref: '#/components/schemas/ObservedAt'
		description: \|
		Timestamp. See clause 4.8.
		type: string
		format: date-time
		$ref: '#/components/schemas/ObservedAt'
		unitCode:
		description: \|
		Property Value's unit code.
		@@ -4710,7 +4764,8 @@ components:
		readOnly: true
		previousValue:
		description: \|
		Previous Property value. Only used in notifications.
		Previous Property value. Only used in notifications, if the showChanges
		option is explicitly requested.
		allOf:
		- oneOf:
		- $ref: '#/components/schemas/DateTimeValue'
		@@ -4766,10 +4821,10 @@ components:
		Context source filter that shall be matched by Context Source Registrations describing
		Context Sources to be used for retrieving Entities.
		type: string
		temporalQ:
		description: \|
		Temporal Query to be present only for "Query Temporal Evolution of Entities" operation (clause 5.7.4).
		$ref: '#/components/schemas/TemporalQuery'
		#temporalQ:
		# description: \|
		# Temporal Query to be present only for "Query Temporal Evolution of Entities" operation (clause 5.7.4).
		# $ref: '#/components/schemas/TemporalQuery'
		scopeQ:
		description: Scope query.
		type: string
		@@ -4867,6 +4922,8 @@ components:
		type: string
		format: uri
		observedAt:
		description: \|
		Timestamp. See clause 4.8.
		$ref: '#/components/schemas/ObservedAt'
		datasetId:
		description: \|
		@@ -4895,7 +4952,8 @@ components:
		readOnly: true
		previousObject:
		description: \|
		Previous Relationship's target object. Only used in notifications.
		Previous Relationship's target object. Only used in notifications, if the showChanges
		option is explicitly requested.
		type: string
		format: uri
		readOnly: true
		@@ -4915,7 +4973,7 @@ components:
		- $ref: '#/components/schemas/Subscription.Periodic'
		Subscription.Common:
		description: \|
		5.2.12 represents a Context Subscription.
		5.2.12 This datatype represents a Context Subscription.
		type: object
		properties:
		id:
		@@ -4978,6 +5036,7 @@ components:
		true indicates that the Subscription is under operation.
		false indicates that the subscription is paused and notifications shall not be delivered.
		type: boolean
		default: true
		notification:
		description: \|
		Notification details.
		@@ -5106,7 +5165,7 @@ components:
		- startAt
		UpdateResult:
		description: \|
		5.2.18 represents the result of Attribute update (append or update) operations
		5.2.18 This datatype represents the result of Attribute update (append or update) operations
		in the NGSI-LD API regardless of whether local or distributed.
		type: object
		properties: