{ "openapi": "3.0.3", "info": { "title": "market-activities-notification", "description": "### ServiceId: S0045\n\n# API Version - 1.0.0\n#### Generated by ECDM Toolkit version 2.12.3\nThis API should be implemented by parties wishing to be informed about updates on the EDSN Market Activities Register.\n# Release History\n\n## 1.0.0 (2025-06-12)\nFirst formal version\n\n## 0.1.0 (2025-03-24)\nFirst draft of API\n", "version": "1.0.0" }, "servers": [ { "url": "/energy-market/market-participant/market-activity/market-activities-notification/v1", "description": "Default host only has API context, name and version," } ], "tags": [ { "name": "EventNotification", "description": "Consumes an event specification according to the CloudEvent standard." } ], "paths": { "/notifications": { "post": { "tags": [ "EventNotification" ], "summary": "Consume a CloudEvent instance.", "description": "The function consumes a CloudEvent instance as specified by the CloudEvent data object. When successfull, the function SHOULD return a 201. Any 400 error code COULD result in the event source issuing a retry, depending on the framework.", "externalDocs": { "description": "Please refer to the documentation referenced below for a more extensive description of the webhook implementation details for Cloud Events.", "url": "https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/http-webhook.md" }, "deprecated": false, "operationId": "notify", "requestBody": { "description": "The event payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudEvent" }, "examples": { "EventExample_N9VZdKZTy8": { "$ref": "#/components/examples/EventExample_N9VZdKZTy8" } } } }, "required": true }, "responses": { "201": { "description": "Created" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "400-Error-Example_UhUW87vzdL": { "$ref": "#/components/examples/400-Error-Example_UhUW87vzdL" } } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "401-Error-Example_Ox7hMSgI9k": { "$ref": "#/components/examples/401-Error-Example_Ox7hMSgI9k" } } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "403-Error-Example_NdO9U7i48s": { "$ref": "#/components/examples/403-Error-Example_NdO9U7i48s" } } } } }, "410": { "description": "Gone", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "410-Error-Example_ULImkNzhK5": { "$ref": "#/components/examples/410-Error-Example_ULImkNzhK5" } } } } }, "429": { "description": "Too Many Requests", "headers": { "Retry_After": { "$ref": "#/components/headers/Retry_After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "429-Error-Example_N6WDVxzNY7": { "$ref": "#/components/examples/429-Error-Example_N6WDVxzNY7" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/application+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "500-Error-Example_QFdLoQTMMS": { "$ref": "#/components/examples/500-Error-Example_QFdLoQTMMS" } } } } }, "501": { "description": "Not Implemented, can be issued by an API Gateway in case the webhook is not (yet) available for use." }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "503-Error-Example_CCVKUXhRzA": { "$ref": "#/components/examples/503-Error-Example_CCVKUXhRzA" } } } } } } } } }, "components": { "headers": { "Retry_After": { "description": "Specifies the time, in seconds, that the server should wait until issuing new events.", "required": true, "deprecated": false, "allowReserved": false, "style": "simple", "explode": false, "schema": { "type": "integer" }, "example": 20 } }, "examples": { "400-Error-Example_UhUW87vzdL": { "summary": "Example of a 400 syntax error.", "value": { "type": "https://cmf.energysector.nl/reference-data/error-catalogue/user-errors/bad-request", "title": "Request contains syntax errors.", "status": 400, "detail": "Parameter- and payload syntax errors prevented the request from being processed.", "instance": "urn:uuid:4017fabc-1b28-11e8-accf-0ed5f89f718b", "traceID": "00-80e1afed08e019fc1110464cfa66635c-7a085853722dc6d2-01", "applicationProblem": [ { "categoryCode": "SYNTAX_ERROR", "severityCode": "ERROR", "message": [ { "identifier": "ERR01", "code": "MISSING", "text": "Required parameters A and B are missing." }, { "identifier": "ERR02", "code": "MISSING", "text": "Required instance of class C2 is missing from payload." } ] } ] } }, "401-Error-Example_Ox7hMSgI9k": { "summary": "Example of a 401 authentication error", "value": { "type": "https://cmf.energysector.nl/reference-data/error-catalogue/default/http-401", "title": "Unauthorized.", "status": 401, "detail": "No access to requested resource." } }, "403-Error-Example_NdO9U7i48s": { "summary": "Example of a 403 authorization error.", "value": { "type": "https://cmf.energysector.nl/reference-data/error-catalogue/default/http-403", "title": "Forbidden.", "status": 403, "detail": "Requester has no permission to perform the requested operation." } }, "410-Error-Example_ULImkNzhK5": { "summary": "Example of a 410 error in case the event sink is no longer operational.", "value": { "type": "https://cmf.energysector.nl/reference-data/error-catalogue/default/http-410", "title": "Gone.", "status": 410, "detail": "Event sink no longer operational." } }, "429-Error-Example_N6WDVxzNY7": { "summary": "Example of a 429 Error example.", "value": { "type": "https://cmf.energysector.nl/reference-data/error-catalogue/default/http-429", "title": "Too many requests.", "status": 429, "detail": "Server is sending events faster then the client can process them." } }, "500-Error-Example_QFdLoQTMMS": { "summary": "Example of a 500 server error.", "value": { "type": "https://cmf.energysector.nl/reference-data/error-catalogue/default/http-500", "title": "Internal Server Error", "status": 500, "detail": "Application encountered a fatal exception." } }, "503-Error-Example_CCVKUXhRzA": { "summary": "Example of a 503 service unavailable error.", "value": { "type": "https://cmf.energysector.nl/reference-data/error-catalogue/default/http-503", "title": "Service Unavailable.", "status": 503, "detail": "Requested endpoint is unreachable at this time." } }, "EventExample_N9VZdKZTy8": { "summary": "Example of an update event including a resource identifier.", "value": { "specversion": "1.0", "id": "c163d014-dfc1-4885-ab0c-a447eff05ffe", "type": "mar.service.deleted", "source": "urn:ean13:87037436423:mar", "time": "2024-03-12T14:01:54.957124Z", "dataversion": "1.0.0", "datacontenttype": "application/json", "data": { "referencedUsagePoint": { "mRID": "123123456789123189", "typeCode": "ACCOUNTINGPOINT" }, "serviceCategory": { "serviceCategoryKind": "C01" }, "dateAndOrTime": { "activationDate": "2024-03-12" } } } } }, "schemas": { "ApplicationMessage": { "title": "ApplicationMessage", "description": "Each ApplicationProblem object can be associated with an array of error messages, represented by ApplicationMessage objects.", "type": "object", "additionalProperties": false, "properties": { "identifier": { "title": "IdentifierType", "description": "A unique, application-specific identification of the message.", "example": "VAL01", "type": "string" }, "code": { "title": "CodeListCodeType", "description": "An application-specific message code.", "example": "PARAM_CONFLICT", "type": "object", "additionalProperties": false, "properties": { "content": { "title": "NormalizedString", "type": "string" }, "_codeListName": { "title": "NormalizedString", "type": "string" }, "_codeListVersion": { "title": "NormalizedString", "type": "string" } }, "required": [ "content" ] }, "text": { "title": "TextType", "description": "Provides a detailed description of the error.", "example": "Parameters A and B can not occur at the same time.", "type": "string" } }, "required": [ "text" ] }, "ApplicationProblem": { "title": "ApplicationProblem", "description": "The ApplicationProblem object provides an extension mechanism for the definition of more complex, structured error messages. It defines an array of error messages associated with a severity- and application-specific error code.", "type": "object", "additionalProperties": false, "properties": { "categoryCode": { "title": "CodeListCodeType", "description": "An application-specific error category code.", "example": "PARAMETER_VALIDATION_ERROR", "type": "object", "additionalProperties": false, "properties": { "content": { "title": "NormalizedString", "type": "string" }, "_codeListName": { "title": "NormalizedString", "type": "string" }, "_codeListVersion": { "title": "NormalizedString", "type": "string" } }, "required": [ "content" ] }, "severityCode": { "title": "ProblemSeverityCodeType", "description": "Identifies the severity of the error.", "example": "ERROR", "type": "string", "default": "ERROR", "enum": [ "INFORMATION", "WARNING", "ERROR", "CRITICAL_ERROR" ] }, "message": { "title": "ApplicationMessage", "type": "array", "items": { "$ref": "#/components/schemas/ApplicationMessage" } } }, "required": [ "categoryCode", "severityCode" ] }, "CloudEvent": { "title": "CloudEvent", "description": "Representation of a CloudEvent header according to the standard defined by CloudEvents.io. This event model has also been embraced by mff/bas and is further defined by the MFF BAS Event Data Specification. Attribute names are according to the CloudEvent standard and thus deviate from the MFF BAS API Standard!", "type": "object", "additionalProperties": false, "properties": { "specversion": { "title": "TextType", "description": "Type: String\nDescription: The version of the CloudEvents specification which the event uses. This enables the interpretation of the context. Compliant event producers MUST use a value of 1.0 when referring to this version of the specification.\nCurrently, this attribute will only have the 'major' and 'minor' version numbers included in it. This allows for 'patch' changes to the specification to be made without changing this property's value in the serialization. Note: for 'release candidate' releases a suffix might be used for testing purposes.\nConstraints:\n- REQUIRED\n- MUST be a non-empty string", "type": "string", "enum": [ "1.0" ] }, "id": { "title": "IdentifierType", "description": "Type: String\nDescription: Identifies the event. Producers MUST ensure that source + id is unique for each distinct event. If a duplicate event is re-sent (e.g. due to a network error) it MAY have the same id. Consumers MAY assume that Events with identical source and id are duplicates.\nIt is strongly advised to use an UUID for uniqueness sake.\nConstraints:\n- REQUIRED\n- MUST be a non-empty string\n- MUST be unique within the scope of the producer", "example": "ead1476d-73c6-4665-91d3-8807dc60aedd", "type": "string" }, "source": { "title": "IdentifierType", "description": "Type: URI-reference\nDescription: Identifies the context in which an event happened. Often this will include information such as the type of the event source, the organization publishing the event or the process that produced the event. The exact syntax and semantics behind the data encoded in the URI is defined by the event producer.\nProducers MUST ensure that source + id is unique for each distinct event.\nAn application MAY assign a unique source to each distinct producer, which makes it easy to produce unique IDs since no other producer will have the same source. The application MAY use UUIDs, URNs, DNS authorities or an application-specific scheme to create unique source identifiers.\nA source MAY include more than one producer. In that case the producers MUST collaborate to ensure that source + id is unique for each distinct event.\nFor the energy sector, the MFF BAS standard defines source as an urn constructed as follows:\nurn:<type-id>:<sender-id>:<source-id> in which:\nType-id identifies how sender-id is formatted and can be either ean13 in case of market parties that have a unique EAN-13, or CoC for those parties identified by their Chamber of Commerce registration ID. \nSender-id contains either the EAN-13 or CoC identification of the originating party. Use the string representation of the CloudEvent_OriginatorIDKind enumeration to assure consistent values for this field.\nSource-id contains a mnemonic name of the service that emitted the event.\nConstraints:\n- REQUIRED\n- MUST be a non-empty URI-reference\n- An absolute URI is RECOMMENDED", "example": "urn:ean13:8716859000003:cmr", "type": "string" }, "type": { "title": "IdentifierType", "description": "Type: String\nDescription: This attribute contains a value describing the type of event related to the originating occurrence. Often this attribute is used for routing, observability, policy enforcement, etc. The format of this is producer defined and might include information such as the version of the type.\nFor the energy sector, the MFF BAS standard defines type as a constructed string as follows:\n<context>.<object>.<operation in which:\nContext identifiers the originating business solution or business domain. Within EDSN, this is the mnemonic name of the solution from which the event originated.\nObject identifies the resource (or business object) that emitted the event. Preferably, this is an NBility business object name but can also be an appropriate CIM object name.\nOperation is the standardized name of the operation that lead to the submission of the event. Use the textual representation of the appropriate entry from CloudEvent_EventKind for consistency.\nConstraints:\n- REQUIRED\n- MUST be a non-empty string", "example": "mdm.meter.modified", "type": "string" }, "datacontenttype": { "title": "IdentifierType", "description": "Type: String per RFC 2046\nDescription: Content type of data value. This attribute enables data to carry any type of content, whereby format and encoding might differ from that of the chosen event format. For example, an event rendered using the JSON envelope format might carry an XML payload in data, and the consumer is informed by this attribute being set to application/xml. The rules for how data content is rendered for different datacontenttype values are defined in the event format specifications.\nFor some binary mode protocol bindings, this field is directly mapped to the respective protocol's content-type metadata property. Normative rules for the binary mode and the content-type metadata mapping can be found in the respective protocol.\nIn some event formats the datacontenttype attribute MAY be omitted. For example, if a JSON format event has no datacontenttype attribute, then it is implied that the data is a JSON value conforming to the application/json media type. In other words: a JSON-format event with no datacontenttype is exactly equivalent to one with datacontenttype=application/json.\nWhen translating an event message with no datacontenttype attribute to a different format or protocol binding, the target datacontenttype SHOULD be set explicitly to the implied datacontenttype of the source.\nConstraints:\n- REQUIRED when a payload is present ('data' property is present), OPTIONAL otherwise.\n- If present, MUST adhere to the format specified in RFC 2046", "example": "application/json", "type": "string" }, "time": { "title": "DateTimeType", "description": "Type: Timestamp\nDescription: Timestamp of the exact date and time at which the event has been generated by the source system. If the time of the occurrence cannot be determined then this attribute MAY be set to some other time (such as the current time) by the CloudEvents producer, however all producers for the same source MUST be consistent in this respect. In other words, either they all use the actual time of the occurrence or they all use the same algorithm to determine the value used.\nConstraints:\n- REQUIRED\n- MUST adhere to the format specified in ISO-8601 with the highest resolution possible and expressed in UTC timezone.", "example": "2023-09-22T14:01:54.957123Z", "type": "string", "format": "date-time" }, "dataversion": { "title": "IdentifierType", "description": "Type: String\nDescription: This is an extension attribute, defined by the MFFBAS CloudEvent standard, which replaces the optional CloudEvent dataschema attribute. The field is used to define the full version of the schema that has been used to create the payload. The schema itself is assumed to be known by the event consumer and this attribute can be used to verify whether this schema is still up-to-date.\nConstraints:\n- REQUIRED when a payload is present ('data' property is present), OPTIONAL otherwise.\n- MUST be a non-empty string when present.", "example": "1.2.1", "type": "string" }, "data": { "$ref": "#/components/schemas/MarketActivityRecord" } }, "required": [ "specversion", "id", "source", "type", "data" ] }, "DateAndOrTime": { "title": "DateAndOrTime", "type": "object", "additionalProperties": false, "properties": { "activationDate": { "title": "DateType", "description": "The date at which the update has become valid.", "example": "2025-02-12", "type": "string", "format": "date" } }, "required": [ "activationDate" ] }, "MarketActivityRecord": { "title": "MarketActivityRecord", "type": "object", "additionalProperties": false, "properties": { "referencedUsagePoint": { "$ref": "#/components/schemas/ReferencedUsagePoint" }, "serviceCategory": { "$ref": "#/components/schemas/ServiceCategory" }, "dateAndOrTime": { "$ref": "#/components/schemas/DateAndOrTime" } }, "required": [ "referencedUsagePoint", "serviceCategory", "dateAndOrTime" ] }, "ProblemDetails": { "title": "ProblemDetails", "description": "The ProblemDetails error response object represents an application error that is compliant with the RFC9457 Problem Details specification.", "type": "object", "additionalProperties": false, "properties": { "type": { "title": "NormalizedString", "description": "The type member is a JSON string containing a URI reference that identifies the problem type. Consumers MUST use the type URI (after resolution, if necessary) as the problem type's primary identifier.\n\nWhen this member is not present, its value is assumed to be about:blank.\n\nIf the type URI is a locator (e.g., those with an http or https scheme), dereferencing it SHOULD provide human-readable documentation for the problem type (e.g., using HTML). However, consumers SHOULD NOT automatically dereference the type URI, unless they do so when providing information to developers (e.g., when a debugging tool is in use).", "example": "https://standards.edsn.nl/REST/error-catalogue/user-errors/parameter-validation", "type": "string" }, "title": { "title": "NameType", "description": "The title member is a JSON string containing a short, human-readable summary of the problem type.\n\nIt SHOULD NOT change from occurrence to occurrence of the problem, except for localization (e.g., using proactive content negotiation).", "example": "One or more parameters did not validate correctly", "type": "string" }, "status": { "title": "IntegerType", "description": "The status member is a JSON number indicating the HTTP status code generated by the origin server for this occurrence of the problem.\n\nThe status member conveys the HTTP status code used for the convenience of the consumer. Generators MUST use the same status code in the actual HTTP response, to assure that generic HTTP software that does not understand this format still behaves correctly.\n\nConsumers can use the status member to determine what the original status code used by the generator was when it has been changed (e.g., by an intermediary or cache) and when a message's content is persisted without HTTP information. Generic HTTP software will still use the HTTP status code.", "example": 400, "type": "integer" }, "detail": { "title": "TextType", "description": "The detail member is a JSON string containing a human-readable explanation specific to this occurrence of the problem.\n\nThe detail string, if present, ought to focus on helping the client correct the problem, rather than giving debugging information.\n\nConsumers SHOULD NOT parse the detail member for information; extensions are more suitable and less error-prone ways to obtain such information.", "example": "Conflicting parameters are: A, B, C, D", "type": "string" }, "instance": { "title": "TextType", "description": "The instance member is a JSON string containing a URI reference that identifies the specific occurrence of the problem.\nWhen the instance URI is dereferenceable, the problem details object can be fetched from it. It might also return information about the problem occurrence in other formats through use of proactive content negotiation.\nWhen the instance URI is not dereferenceable, it serves as a unique identifier for the problem occurrence that may be of significance to the server but is opaque to the client.", "example": "urn:uuid:4017fabc-1b28-11e8-accf-0ed5f89f718b", "type": "string" }, "traceId": { "title": "IdentifierType", "description": "This field provides an OpenTelemetry compliant trace identifier that can be used to correlate related (error) messages. The field is constructed as follows:\n{version}-{trace_id}-{span_id}-{trace_flags}\nIn which:\nversion = version of this trace;\ntrace-id = identification of a single trace (i.e. associated series of messages);\nspan-id = identification of a series of correlated messages within a single trace;\ntrace-flags = additional information.", "example": "00-80e1afed08e019fc1110464cfa66635c-7a085853722dc6d2-01", "type": "string" }, "applicationProblem": { "title": "ApplicationProblem", "type": "array", "items": { "$ref": "#/components/schemas/ApplicationProblem" } } }, "required": [ "type", "title", "status" ] }, "ReferencedUsagePoint": { "title": "ReferencedUsagePoint", "description": "Reference to a UsagePoint (AccountingPoint OR MarketEvaluationPoint).", "type": "object", "additionalProperties": false, "properties": { "mrid": { "title": "Ean18Type", "description": "EAN18 code of the (primary or secondary) Allocation Point (AccountingPoint) OR the Connection (MarketEvaluationPoint) in the connections register.", "example": "001234560000000018", "type": "string", "pattern": "^[0-9]{18}$" }, "typeCode": { "title": "UsagePointType", "description": "TypeCode for the EAN18 type.", "example": "MARKETEVALUATIONPOINT", "type": "string", "enum": [ "MARKETEVALUATIONPOINT", "ACCOUNTINGPOINT" ] } }, "required": [ "mrid", "typeCode" ] }, "ServiceCategory": { "title": "ServiceCategory", "description": "Provided service information.", "type": "object", "additionalProperties": false, "properties": { "serviceCategoryKind": { "title": "ServiceCategoryKindCode", "description": "Services are categorized in logical groups (e.g. Congestion Management, Metering, ...). The service category kind returns an encoding of the category associated with the returned service kind.\nValue must be one of:\nC01 - Congestion management;\nC02 - Energy supply;\nC03 - Metering;\nC04 - Balance responsible;\nC05 - Balance management;", "example": "C01", "type": "string", "enum": [ "C01", "C02", "C03", "C04", "C05" ] } }, "required": [ "serviceCategoryKind" ] } } } }