diff --git a/.github/workflows/docs-latest.yml b/.github/workflows/docs-latest.yml index 47bdbfb8..938128cf 100644 --- a/.github/workflows/docs-latest.yml +++ b/.github/workflows/docs-latest.yml @@ -2,14 +2,22 @@ # # SPDX-License-Identifier: Apache-2.0 -name: docs-latest +name: docs-publish on: push: branches: - main + # Fork preview only; remove this branch before merging upstream. + - migration/versioned-publishing + release: + types: + - published permissions: contents: write +concurrency: + group: docs-publish + cancel-in-progress: false jobs: deploy: runs-on: ubuntu-latest @@ -28,9 +36,17 @@ jobs: run: | pip install poetry poetry install --no-interaction - - name: Configure fake git user to associate commits + - name: Build all documentation versions run: | - git config --global user.name Docs deploy - git config --global user.email docs-action@shapshifter - - name: Push the main branch under the alias development - run: poetry run mike deploy --push --update-aliases development + if [[ "$GITHUB_EVENT_NAME" == release ]]; then + export ENABLE_PDF_EXPORT=1 + fi + SITE_BASE_URL="https://${GITHUB_REPOSITORY_OWNER}.github.io/${GITHUB_REPOSITORY#*/}/" \ + bash scripts/build-docs.sh + - name: Publish site to gh-pages + uses: peaceiris/actions-gh-pages@v4 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_branch: gh-pages + publish_dir: ./site + force_orphan: true diff --git a/.github/workflows/docs-pr.yml b/.github/workflows/docs-pr.yml index 05281df6..c48b0a78 100644 --- a/.github/workflows/docs-pr.yml +++ b/.github/workflows/docs-pr.yml @@ -26,7 +26,7 @@ jobs: pip install poetry poetry install --no-interaction - name: Create local documentation build - run: poetry run mkdocs build + run: bash scripts/build-docs.sh - name: Archive reports uses: actions/upload-artifact@v4 with: diff --git a/.github/workflows/docs-release.yml b/.github/workflows/docs-release.yml deleted file mode 100644 index 6493bdb2..00000000 --- a/.github/workflows/docs-release.yml +++ /dev/null @@ -1,40 +0,0 @@ -# Copyright Contributors to the Shapeshifter project -# -# SPDX-License-Identifier: Apache-2.0 - -name: docs-release - -on: - release: - types: - - published -permissions: - contents: write -jobs: - deploy: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v6 - with: - fetch-depth: 0 # checkout branch history required to update - - uses: actions/setup-python@v5 - with: - python-version: 3.12 - - uses: actions/cache@v4 - with: - key: ${{ github.ref }} - path: .cache - - name: Install Poetry and dependencies - run: | - pip install poetry - poetry install --no-interaction - - name: Configure fake git user to associate commits - run: | - git config --global user.name Docs deploy - git config --global user.email docs-action@shapshifter - - name: Push the verisioned documentation with alias latest - run: poetry run mike deploy --push --update-aliases ${{ github.event.release.tag_name }} latest - env: - ENABLE_PDF_EXPORT: 1 - - name: Set latest as default (should only have te be run once) - run: poetry run mike set-default --push latest diff --git a/.gitignore b/.gitignore index 95fa076c..6b22f95c 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,7 @@ .idea/ site/ +*.code-workspace # Created by https://www.toptal.com/developers/gitignore/api/windows,python,libreoffice,emacs,microsoftoffice # Edit at https://www.toptal.com/developers/gitignore?templates=windows,python,libreoffice,emacs,microsoftoffice diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4962af3e..6a862bb9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,7 +17,7 @@ For more information see the projects used to render and upload the documentatio - [MkDocs](https://www.mkdocs.org/) the rendering engine - [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) the theme - [PlantUML for MkDocs](https://pypi.org/project/mkdocs-plantuml/) plugin to render PlantUML diagrams -- [Mike](https://github.com/jimporter/mike) to publish multiple versions +- A static build script to publish each versioned documentation folder under its own URL Besides the technical features, here are some brief recommendations on using Markdown: @@ -51,3 +51,9 @@ Or build it once so you end up with the generated HTML in the `site/` folder: ``` $ poetry run mkdocs build ``` + +To build all published versions and the root redirect to development, run: + +``` +$ bash scripts/build-docs.sh +``` diff --git a/README.md b/README.md index 77704fd6..04e1cb5e 100644 --- a/README.md +++ b/README.md @@ -29,5 +29,11 @@ ordering, and settlement processes. UFTP and the USEF Framework are developed, maintained and audited by the USEF Foundation. -The directory name of each set of XSDs refer to the corresponding version of USEF Flexibility Trading Protocol Specifications as published -by the [USEF Foundation](https://www.usef.energy/). +XSDs are organized by specification version under `specifications//xsd/`. +Numbered directories preserve released snapshots; the current draft is under +[`specifications/development/xsd/`](specifications/development/xsd/). Relative +schema includes resolve within each version's XSD directory. + +Browsable Markdown and its image assets are stored alongside each version under +`specifications//docs/`. The version-specific README records the source +tag or commit for each snapshot. diff --git a/VERSIONING.md b/VERSIONING.md new file mode 100644 index 00000000..06852f02 --- /dev/null +++ b/VERSIONING.md @@ -0,0 +1,46 @@ +# Specification Versioning and Publishing + +## Version policy + +The versioned directory is the source of truth for each specification snapshot: + +```text +specifications/ + 1.0.1/ + 2.0.0/ + 3.0.0/ + 3.1.0/ + development/ +``` + +Each directory contains its own documentation and XSDs, plus release artifacts when available. Numbered releases are immutable after publication. `development` is the mutable draft following the latest numbered release; its content must not be presented as a numbered release. + +The canonical documentation paths are `/1.0.1/`, `/2.0.0/`, `/3.0.0/`, `/3.1.0/`, and `/development/`. The site root redirects to `/development/`. The version selector links between versions. + +All editable specification Markdown and images belong under `specifications//docs/`; the development source is `specifications/development/docs/`. Keep XSD includes and Markdown image references within their version directory. Do not maintain a duplicate root `docs/` or `xsd/` source. + +## Publishing + +The `docs-publish` workflow builds each versioned documentation tree as a static site and publishes the complete site to the `gh-pages` branch. `scripts/build-docs.sh` writes the sites to their matching version paths and generates the root `versions.json` consumed by Material's native version selector. The root `index.html` redirects to the development site. + +The workflow publishes on pushes to `main` and published releases. A fork-only preview trigger for `migration/versioned-publishing` is currently retained; remove that temporary trigger before merging the workflow upstream. + +For a release, copy the approved development documentation, images, and XSDs into a new numbered directory, add available release artifacts, and record their provenance. Never change the content behind an already published numbered path. Verify relative references and the rendered site before publishing. + +## Historical provenance + +The `V3.0.0` and `V3.1.0` tags are authoritative for their XSDs and release artifacts. Those tags predate or do not contain the Markdown conversion, so the Markdown snapshots use the nearest reviewed documentation commits. The v1.0.1 and v2.0.0 XSDs are reconstructed from their historical commits. + +| Version or artifact | Source | Preserved content | +| --- | --- | --- | +| v1.0.1 XSDs | [Commit `e12a4f9`](https://github.com/shapeshifter/shapeshifter-specification/commit/e12a4f9293075ee369b62c7bb0e3cf08ea57b450) | Complete v1.0.1 XSD set from the historical `V1.01/` directory; the README was added later. | +| v2.0.0 XSDs | [Commit `cc7a362`](https://github.com/shapeshifter/shapeshifter-specification/commit/cc7a362d86ac693e130091a5c9376bf2d848ee2c) | Complete v2.0.0 XSD set. | +| v3.0.0 XSDs and release artifacts | [`V3.0.0`, commit `2b2f8f3`](https://github.com/shapeshifter/shapeshifter-specification/tree/2b2f8f394eeab7a47f14e31593bd6634f37621bc) | Tagged XSDs and release documents. The PDF and Word files were introduced in [commit `7068732`](https://github.com/shapeshifter/shapeshifter-specification/commit/7068732d31d059e13e8dafd1cc5d5e89866d9e8b). | +| v3.0.0 Markdown and images | [Commit `24da5e2`](https://github.com/shapeshifter/shapeshifter-specification/commit/24da5e2d8443108a23aaceca8a8215330fb0c65b) | First complete, reviewed Markdown conversion and image assets (2023-02-20). | +| v3.1.0 XSDs and release artifacts | [`V3.1.0`, commit `3078c25`](https://github.com/shapeshifter/shapeshifter-specification/tree/3078c25a067c641dacd38ae8bde1ba4b4fe48413) | Tagged XSDs and release documents. | +| v3.1.0 Markdown and images | [Commit `92ef001`](https://github.com/shapeshifter/shapeshifter-specification/commit/92ef001b79c6312403e4e463bcbc827c14f5a389) | Documentation state immediately preceding the v3.1.0 release (2025-04-30). | +| Development Markdown and images | [Commit `38b40f3`](https://github.com/shapeshifter/shapeshifter-specification/commit/38b40f36316395d169b446cd156a567dd117ae36) | Mutable documentation immediately before it was moved under `specifications/development/`. | +| Development XSDs | [Commit `f799cac`](https://github.com/shapeshifter/shapeshifter-specification/commit/f799cac9867c473fc4a4d18a0db046d577bada0c) | Mutable XSDs immediately before they were moved under `specifications/development/`. | +| Markdown specification and publishing | [PR #67](https://github.com/shapeshifter/shapeshifter-specification/pull/67), later refined | MkDocs, Material for MkDocs, and GitHub Actions publishing history. | + +Preserve these commit and tag references even for historical versions that were not published as GitHub Releases. Migration-added READMEs and shared `docs/versions.md` indexes are metadata rather than part of the historical source snapshots. diff --git a/mkdocs-archive.yml b/mkdocs-archive.yml new file mode 100644 index 00000000..131958c3 --- /dev/null +++ b/mkdocs-archive.yml @@ -0,0 +1,4 @@ +INHERIT: mkdocs.yml + +nav: + - Shapeshifter Specification: index.md \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 51849173..3f864b00 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,10 +4,10 @@ site_name: Shapeshifter specification repo_url: https://github.com/shapeshifter/shapeshifter-specification -site_url: http://localhost:8000/ +site_url: !ENV [SITE_URL, "http://localhost:8000/"] site_author: "Contributors to the Shapeshifter project" copyright: "Copyright 2020-2025 Contributors to the Shapeshifter project" -docs_dir: docs/ +docs_dir: !ENV [DOCS_DIR, "specifications/development/docs/"] theme: name: material features: @@ -17,8 +17,7 @@ theme: - navigation.top # back-to-top button when scrolling back up logo: assets/images/shapeshifter-icon-white.svg favicon: assets/images/shapeshifter-icon-color.svg - # TODO: enable this feature once versioned releases have been published - # custom_dir: overrides # to add the warning bar for the latest version + custom_dir: overrides extra: version: default: development @@ -43,7 +42,6 @@ plugins: width: 50vw skip_classes: - no-lightbox - - mike - plantuml-colocator markdown_extensions: - admonition # for Recommended Practice blocks @@ -117,3 +115,4 @@ nav: - Flex reservation mechanism: appendix/flex-reservation-mechanism.md - Message transport mechanism: appendix/message-transport-mechanism.md - Bibliography: appendix/bibliography.md + - Versioned specification files: versions.md diff --git a/poetry.lock b/poetry.lock index 4faa54cf..778bede9 100644 --- a/poetry.lock +++ b/poetry.lock @@ -696,28 +696,6 @@ files = [ {file = "mergedeep-1.3.4.tar.gz", hash = "sha256:0096d52e9dad9939c3d975a774666af186eda617e6ca84df4c94dec30004f2a8"}, ] -[[package]] -name = "mike" -version = "1.1.2" -description = "Manage multiple versions of your MkDocs-powered documentation" -optional = false -python-versions = "*" -groups = ["main"] -files = [ - {file = "mike-1.1.2-py3-none-any.whl", hash = "sha256:4c307c28769834d78df10f834f57f810f04ca27d248f80a75f49c6fa2d1527ca"}, - {file = "mike-1.1.2.tar.gz", hash = "sha256:56c3f1794c2d0b5fdccfa9b9487beb013ca813de2e3ad0744724e9d34d40b77b"}, -] - -[package.dependencies] -jinja2 = "*" -mkdocs = ">=1.0" -pyyaml = ">=5.1" -verspec = "*" - -[package.extras] -dev = ["coverage", "flake8 (>=3.0)", "shtab"] -test = ["coverage", "flake8 (>=3.0)", "shtab"] - [[package]] name = "mkdocs" version = "1.6.1" @@ -1287,21 +1265,6 @@ h2 = ["h2 (>=4,<5)"] socks = ["pysocks (>=1.5.6,!=1.5.7,<2.0)"] zstd = ["zstandard (>=0.18.0)"] -[[package]] -name = "verspec" -version = "0.1.0" -description = "Flexible version handling" -optional = false -python-versions = "*" -groups = ["main"] -files = [ - {file = "verspec-0.1.0-py3-none-any.whl", hash = "sha256:741877d5633cc9464c45a469ae2a31e801e6dbbaa85b9675d481cda100f11c31"}, - {file = "verspec-0.1.0.tar.gz", hash = "sha256:c4504ca697b2056cdb4bfa7121461f5a0e81809255b41c03dda4ba823637c01e"}, -] - -[package.extras] -test = ["coverage", "flake8 (>=3.7)", "mypy", "pretend", "pytest"] - [[package]] name = "watchdog" version = "6.0.0" @@ -1470,4 +1433,4 @@ test = ["pytest"] [metadata] lock-version = "2.1" python-versions = "^3.10" -content-hash = "86c4d2ae50e76bc0c3bb679822028af5b104bcec7218e163b1860e3df21aa903" +content-hash = "437e7f946098041c7685d60d567c3bc76a6e7d50f1b6b9f8eba20f54ef302511" diff --git a/pyproject.toml b/pyproject.toml index b87d86b2..770c8cba 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -15,7 +15,6 @@ packages = [{include = "shapeshifter_specification"}] [tool.poetry.dependencies] python = "^3.10" mkdocs-material = "^9.6.12" -mike = "^1.1.2" mkdocs-glightbox = "^0.4.0" setuptools = "^70.3.0" weasyprint = "^65.1" diff --git a/scripts/build-docs.sh b/scripts/build-docs.sh new file mode 100644 index 00000000..f33a9739 --- /dev/null +++ b/scripts/build-docs.sh @@ -0,0 +1,84 @@ +#!/usr/bin/env bash +# Copyright Contributors to the Shapeshifter project +# SPDX-License-Identifier: Apache-2.0 + +set -euo pipefail + +site_dir="${1:-site}" +site_base_url="${SITE_BASE_URL:-http://localhost:8000/}" +tmp_dir="$(mktemp -d)" +trap 'rm -rf "$tmp_dir"' EXIT +versions=(development) + +versioned_dirs=() +for docs_dir in specifications/[0-9]*/docs; do + [[ -d "$docs_dir" ]] || continue + versioned_dirs+=("$(basename "$(dirname "$docs_dir")")") +done + +while IFS= read -r version; do + [[ -n "$version" ]] && versions+=("$version") +done < <(printf '%s\n' "${versioned_dirs[@]}" | python3 -c 'import sys; versions = [line.strip() for line in sys.stdin if line.strip()]; versions.sort(key=lambda version: tuple(int(part) for part in version.split(".")), reverse=True); print("\n".join(versions))') + +mkdir -p "$site_dir" + +for version in "${versions[@]}"; do + docs_dir="specifications/$version/docs" + test -d "$docs_dir" + build_docs_dir="$docs_dir" + config_file="mkdocs.yml" + if [[ "$version" == "1.0.1" || "$version" == "2.0.0" ]]; then + config_file="mkdocs-archive.yml" + build_docs_dir="$tmp_dir/$version/docs" + mkdir -p "$build_docs_dir/xsd" + cp -R "$docs_dir/." "$build_docs_dir/" + cp -R "specifications/$version/xsd/." "$build_docs_dir/xsd/" + fi + SITE_URL="${site_base_url}${version}/" \ + DOCS_DIR="$build_docs_dir" \ + poetry run mkdocs build --strict --config-file "$config_file" --site-dir "$site_dir/$version" +done + +printf '%s\n' "${versions[@]}" | python3 -c ' +import json +import sys + +versions = [line.strip() for line in sys.stdin if line.strip()] +json.dump( + [ + { + "version": version, + "title": "Development (unreleased)" if version == "development" else version, + "aliases": [], + } + for version in versions + ], + sys.stdout, + indent=2, +) +sys.stdout.write("\n") +' > "$site_dir/versions.json" + +{ +cat <<'HTML' + + + + + + + Redirecting to the development specification + + +
+

Shapeshifter specification

+

Redirecting to the development specification.

+

If you are not redirected, continue to + Development (unreleased). +

+
+ + +HTML +} > "$site_dir/index.html" +touch "$site_dir/.nojekyll" diff --git a/specifications/1.0.1/README.md b/specifications/1.0.1/README.md new file mode 100644 index 00000000..217edd0b --- /dev/null +++ b/specifications/1.0.1/README.md @@ -0,0 +1,7 @@ +# Shapeshifter Specification 1.0.1 + +This directory preserves the v1.0.1 XSD snapshot from the historical `V1.01/` directory. + +Source commit: [`e12a4f9293075ee369b62c7bb0e3cf08ea57b450`](https://github.com/shapeshifter/shapeshifter-specification/commit/e12a4f9293075ee369b62c7bb0e3cf08ea57b450) + +The original XSD filenames and schema references are retained. Do not edit this snapshot; make specification changes in the development sources and publish them as a new version. \ No newline at end of file diff --git a/specifications/1.0.1/docs/index.md b/specifications/1.0.1/docs/index.md new file mode 100644 index 00000000..af2b92a9 --- /dev/null +++ b/specifications/1.0.1/docs/index.md @@ -0,0 +1,13 @@ +# Shapeshifter Specification 1.0.1 + +This historical release is preserved as XML Schema Definition (XSD) files. The original filenames and schema references are retained. + +## XSD files + +- [UFTP-V1.01-agr-cro.xsd](xsd/UFTP-V1.01-agr-cro.xsd) +- [UFTP-V1.01-agr-dso.xsd](xsd/UFTP-V1.01-agr-dso.xsd) +- [UFTP-V1.01-agr.xsd](xsd/UFTP-V1.01-agr.xsd) +- [UFTP-V1.01-common.xsd](xsd/UFTP-V1.01-common.xsd) +- [UFTP-V1.01-cro-dso.xsd](xsd/UFTP-V1.01-cro-dso.xsd) +- [UFTP-V1.01-cro.xsd](xsd/UFTP-V1.01-cro.xsd) +- [UFTP-V1.01-dso.xsd](xsd/UFTP-V1.01-dso.xsd) \ No newline at end of file diff --git a/specifications/1.0.1/xsd/UFTP-V1.01-agr-cro.xsd b/specifications/1.0.1/xsd/UFTP-V1.01-agr-cro.xsd new file mode 100644 index 00000000..a38c2e9a --- /dev/null +++ b/specifications/1.0.1/xsd/UFTP-V1.01-agr-cro.xsd @@ -0,0 +1 @@ + Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. A connection that the AGR want the CRO to update EntityAddress of the Connection entity being updated. The first Period hat the AGR represents the prosumer at this Connection. The last Period that the AGR represents the prosumer at this Connection, if applicable. MessageID of the AGRPortfolioUpdate that has just been accepted or rejected Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. The Period for which the AGR requests the portfolio information. Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. MessageID of the AGRPortfolioQuery that has just been accepted or rejected The Period that the portfolio is valid. EntityAddress of the CongestionPoint. Indicates whether the DSO accepts mutual exclusive FlexOffers on this CongestionPoint. Indicates which party is responsible for day-ahead redispatch. Indicates which party is responsible for intraday ahead redispatch, AGR or DSO. If not specified, there will be no intraday trading on this CongestionPoint. EntityAddress of the Connection. \ No newline at end of file diff --git a/specifications/1.0.1/xsd/UFTP-V1.01-agr-dso.xsd b/specifications/1.0.1/xsd/UFTP-V1.01-agr-dso.xsd new file mode 100644 index 00000000..3224c0c2 --- /dev/null +++ b/specifications/1.0.1/xsd/UFTP-V1.01-agr-dso.xsd @@ -0,0 +1 @@ + ISO 8601 time interval (minutes only, for example PT15M) indicating the duration of the ISPs referenced in this message. Although the ISP length is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant ISP duration. Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. Day (in yyyy-mm-dd format) the ISPs referenced in this Flex* message belong to. Entity Address of the Congestion Point this D-Prognosis applies to. The ISP represents one or more Imbalance Settlement Periods and is used by Prognosis and Flex-related messages. Revision of this message. A sequence number that must be incremented each time a new revision of a prognosis is sent. The combination of SenderDomain and PrognosisSequence should be unique Power specified for this ISP in Watts. Also see the important notes about the sign of this attribute in the main documentation entry for the ISP element. Number of the first ISPs this element refers to. The first ISP of a day has number 1. The number of the ISPs this element represents. Optional, default value is 1. MessageID of the D-Prognosis message this request is based on. The ISP represents one or more Imbalance Settlement Periods and is used by Prognosis and Flex-related messages. Reference to the bilateral contract in question. Message reference, assigned by the DSO originating the FlexReservationUpdate. Remaining reserved power specified for this ISP in Watts. Number of the first ISPs this element refers to. The first ISP of a day has number 1. The number of the ISPs this element represents. Optional, default value is 1. MessageID of the FlexReservationUpdate message this request is based on. The ISP represents one or more Imbalance Settlement Periods and is used by Prognosis and Flex-related messages. Revision of this message, a sequence number that must be incremented each time a new revision of a FlexRequest message is sent. Date and time, including the time zone (ISO 8601 formatted as per http://www.w3.org/TR/NOTE-datetime) until which the FlexRequest message is valid. Power specified for this ISP in Watts. Also see the important notes about the sign of this attribute in the main documentation entry for the ISP element. Power specified for this ISP in Watts. Also see the important notes about the sign of this attribute in the main documentation entry for the ISP element. Number of the first ISPs this element refers to. The first ISP of a day has number 1. The number of the ISPs this element represents. Optional, default value is 1. MessageID of the FlexRequest message this request is based on. If the DSO does not support mutually exclusive offers it will reject FlexOffers that contain more than one OfferOption. Date and time, including the time zone (ISO 8601 formatted as per http://www.w3.org/TR/NOTE-datetime) until which the FlexOffer is valid. MessageID of the FlexRequest message this request is based on. Reference to the concerning bilateral contract, if applicable. MessageID of the D-Prognosis this request is based on, if it has been agreed that the baseline is based on D-prognoses. Identification of the baseline prognosis, if another baseline methodology is used than based on D-prognoses ISO 4217 code indicating the currency that applies to the price of the FlexOffer. The ISP represents one or more Imbalance Settlement Periods and is used by Prognosis and Flex-related messages. The identification of this option. The asking price for the flexibility offered in this option. The minimal activation factor for this OfferOption. An AGR may choose to include MinActivationFactor in FlexOffers even if the DSO is not interested in partial activation. In that case the DSO will simply use an ActivationFactor of 1.00 in every FlexOrder. Power specified for this ISP in Watts. Also see the important notes about the sign of this attribute in the main documentation entry for the ISP element. Number of the first ISPs this element refers to. The first ISP of a day has number 1. The number of the ISPs this element represents. Optional, default value is 1. MessageID of the FlexOffer message this request is based on. MessageID of the FlexOffer message that is being revoked: this FlexOffer must have been accepted previously. MessageID of the FlexOfferRevocation message this request is based on. The ISP represents one or more Imbalance Settlement Periods and is used by Prognosis and Flex-related messages. MessageID of the FlexOffer message this order is based on. Reference to the concerning bilateral contract, if applicable. MessageID of the D-Prognosis this request is based on, if it has been agreed that the baseline is based on D-prognoses. Identification of the baseline prognosis, if another baseline methodology is used than based on D-prognoses The price for the flexibility ordered. Usually, the price should match the price of the related FlexOffer. ISO 4217 code indicating the currency that applies to the price of the FlexOffer. Order number assigned by the DSO originating the FlexOrder. To be stored by the AGR and used in the settlement phase. The OptionReference from the OfferOption chosen from the FlexOffer. The activation factor for this OfferOption. The ActivationFactor must be greater than or equal to the MinActivationFactor in the OfferOption chosen from the FlexOffer. Power specified for this ISP in Watts. Also see the important notes about the sign of this attribute in the main documentation entry for the ISP element. Number of the first ISPs this element refers to. The first ISP of a day has number 1. The number of the ISPs this element represents. Optional, default value is 1. MessageID of the FlexOrder that has just been accepted or rejected. First Period of the settlement period this message applies to. Last Period of the settlement period this message applies to. Settlement reference, assigned by the DSO originating the FlexSettlement. ISO 4217 code indicating the currency that applies to all amounts (flex price, penalty and net settlement) in this message. Reference to the concerning bilateral contract, if it is linked to it MessageID of the Prognosis message (more specifically: the D-Prognosis) the FlexOrder is based on, if it has been agreed that the baseline is based on D-prognoses. Identification of the baseline prognosis, if another baseline methodology is used than based on D-prognoses. Entity Address of the Congestion Point the FlexOrder applies to. The price accepted for supplying the ordered amount of flexibility as per the referenced FlexOrder messages. Penalty due a non-zero PowerDeficiency Net settlement amount for this Period: Price minus Penalty. Number of the first ISPs this element refers to. The first ISP of a day has number 1. The number of the ISPs this element represents. Optional, default value is 1. Power originally forecast (as per the referenced baseline) for this ISP in Watts. Amount of flex power ordered (as per the referenced FlexOrder message) for this ISP in Watts. Actual amount of power for this ISP in Watts, as measured/determined by the DSO and allocated to the AGR. Actual amount of flex power delivered for this ISP in Watts, as determined by the DSO. Amount of flex power sold but not delivered for this ISP in Watts, as determined by the DSO. The ISP represents one or more Imbalance Settlement Periods and is used by Prognosis and Flex-related messages. MessageID of the FlexSettlemnet message that has just been accepted or rejected Reference included in the FlexSettlement that has just been received. Order reference assigned by the DSO when originating the FlexOrder. Indication whether the AGR accepts the order settlement details provided by the DSO (and will invoice accordingly), or disputes these details. In case the order settlement was disputed, this attribute must contain a human-readable description of the reason. Reference to the concerning bilateral contract. Period the being settled. Number of the first ISPs this element refers to. The first ISP of a day has number 1. The number of the ISPs this element represents. Optional, default value is 1. Amount of flex power that has been reserved (and not released using a FlexReservationUpdate message). Amount of flex power that has been both reserved in advance and has been requested using a FlexRequest (i.e. the lowest amount of flex power for this ISP). If there was no FlexRequest, this field is omitted. Amount of flex power that is considered available based on the FlexRequest in question. In case RequestedPower=0, AvailablePower is defined so that the offered power is allowed to be between 0 and AvailablePower in terms of compliancy (see Appendix 3 for details). In case RequestedPower ≠0, AvailablePower is defined so that the offered power is allowed to exceed the amount of requested power up to AvailablePower. If this is relevant for settlement, the DSO can include this field. Amount of flex power that has been reserved in advance, requested using a FlexRequest and covered in an offer from the AGR. If there was no offer, this field is omitted. If there were multiple offers, only the one is considered that is most compliant . Amount of flex power that has been ordered using a FlexOrder message that was based on a FlexOffer, both linked to this contract. If there was no order, this field is omitted. \ No newline at end of file diff --git a/specifications/1.0.1/xsd/UFTP-V1.01-agr.xsd b/specifications/1.0.1/xsd/UFTP-V1.01-agr.xsd new file mode 100644 index 00000000..96b850c3 --- /dev/null +++ b/specifications/1.0.1/xsd/UFTP-V1.01-agr.xsd @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/specifications/1.0.1/xsd/UFTP-V1.01-common.xsd b/specifications/1.0.1/xsd/UFTP-V1.01-common.xsd new file mode 100644 index 00000000..c26c7c6c --- /dev/null +++ b/specifications/1.0.1/xsd/UFTP-V1.01-common.xsd @@ -0,0 +1 @@ + The SignedMessage element represents the secure wrapper used to submit USEF XML messages from the local message queue to the message queue of a remote participant. It contains minimal metadata (which is distinct from the common metadata used for all other messages), allowing the recipient to look up the sender's cryptographic scheme and public keys, and the actual XML message, as transformed (signed/sealed) using that cryptographic scheme. The Internet domain of the USEF participant sending this message. Upon receiving a message, the recipient should validate that its value matches the corresponding attribute value specified in the inner XML message, once un-sealed: if not, the message must be rejected as invalid. The USEF role of the participant sending this message: AGR, BRP, CRO, DSO or MDC. Receive-time validation should take place as described for the SenderDomain attribute above. The Base-64 encoded inner XML message contained in this wrapper, as transformed (signed/sealed) using the sender's cryptographic scheme. The recipient can determine which scheme applies using a DNS or configuration file lookup, based on the combination of SenderDomain and SenderRole. The Internet domain of the USEF participant sending this message. When receiving a message, its value should match the value specified in the SignedMessage wrapper: otherwise, the message must be rejected as invalid. When replying to this message, this attribute is used to look up the USEF endpoint the reply message should be delivered to. Internet domain of the participant this message is intended for. When sending a message, this attribute, combined with the RecipientRole, is used to look up the USEF endpoint the message should be delivered to. Date and time this message was created, including the time zone (ISO 8601 formatted as per http://www.w3.org/TR/NOTE-datetime). Unique identifier (UUID/GUID as per IETF RFC 4122) for this message, to be generated when composing each message. Unique identifier (UUID/GUID as per IETF RFC 4122) used to correlate responses with requests, to be generated when composing the first message in a conversation and subsequently copied from the original message to each reply message. Indication whether the query was executed successfully or failed. In case the query failed, this attribute must contain a human-readable description of the failure reason. \ No newline at end of file diff --git a/specifications/1.0.1/xsd/UFTP-V1.01-cro-dso.xsd b/specifications/1.0.1/xsd/UFTP-V1.01-cro-dso.xsd new file mode 100644 index 00000000..914e0cbc --- /dev/null +++ b/specifications/1.0.1/xsd/UFTP-V1.01-cro-dso.xsd @@ -0,0 +1 @@ + Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. A congestion point that the DSO wants the CRO to update EntityAddress of the Connection. The first Period that the Connection is part of this CongestionPoint. The last Period that the Connection is part of this CongestionPoint. Indicates whether the DSO accepts mutual exclusive FlexOffers on this CongestionPoint. Indicates which party is responsible for day-ahead redispatch. Indicates which party is responsible for intraday ahead redispatch, AGR or DSO. If not specified, there will be no intraday trading on this CongestionPoint. A connection that the DSO wants the CRO to update EntityAddress of the Connection. The first Period that the Connection is part of this CongestionPoint. The last Period that the Connection is part of this CongestionPoint. MessageID of the DSOPortfolioUpdateResponse that has just been accepted or rejected Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. The Period for which the AGR requests the portfolio information. EntityAddress of the CongestionPoint MessageID of the AGRPortfolioQuery that has just been accepted or rejected Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. The Period for which the AGR requests the portfolio information. EntityAddress of the Connection. A Connection that is part of the congestion point. EntityAddress of the Connection. The internet domain of the AGR that represents the prosumer connected on this Connection, if applicable. \ No newline at end of file diff --git a/specifications/1.0.1/xsd/UFTP-V1.01-cro.xsd b/specifications/1.0.1/xsd/UFTP-V1.01-cro.xsd new file mode 100644 index 00000000..5a307084 --- /dev/null +++ b/specifications/1.0.1/xsd/UFTP-V1.01-cro.xsd @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/specifications/1.0.1/xsd/UFTP-V1.01-dso.xsd b/specifications/1.0.1/xsd/UFTP-V1.01-dso.xsd new file mode 100644 index 00000000..c150e080 --- /dev/null +++ b/specifications/1.0.1/xsd/UFTP-V1.01-dso.xsd @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/specifications/2.0.0/README.md b/specifications/2.0.0/README.md new file mode 100644 index 00000000..f6024a83 --- /dev/null +++ b/specifications/2.0.0/README.md @@ -0,0 +1,7 @@ +# Shapeshifter Specification 2.0.0 + +This directory preserves the v2.0.0 XSD snapshot from the historical `V2.00/` directory. + +Source commit: [`cc7a362d86ac693e130091a5c9376bf2d848ee2c`](https://github.com/shapeshifter/shapeshifter-specification/commit/cc7a362d86ac693e130091a5c9376bf2d848ee2c) + +The original XSD filenames and schema references are retained. Do not edit this snapshot; make specification changes in the development sources and publish them as a new version. \ No newline at end of file diff --git a/specifications/2.0.0/docs/index.md b/specifications/2.0.0/docs/index.md new file mode 100644 index 00000000..423fff4c --- /dev/null +++ b/specifications/2.0.0/docs/index.md @@ -0,0 +1,14 @@ +# Shapeshifter Specification 2.0.0 + +This historical release is preserved as XML Schema Definition (XSD) files. The original filenames and schema references are retained. + +## XSD files + +- [UFTP-V2.00-agr-cro.xsd](xsd/UFTP-V2.00-agr-cro.xsd) +- [UFTP-V2.00-agr-dso.xsd](xsd/UFTP-V2.00-agr-dso.xsd) +- [UFTP-V2.00-agr.xsd](xsd/UFTP-V2.00-agr.xsd) +- [UFTP-V2.00-common.xsd](xsd/UFTP-V2.00-common.xsd) +- [UFTP-V2.00-cro-dso.xsd](xsd/UFTP-V2.00-cro-dso.xsd) +- [UFTP-V2.00-cro.xsd](xsd/UFTP-V2.00-cro.xsd) +- [UFTP-V2.00-dso.xsd](xsd/UFTP-V2.00-dso.xsd) +- [UFTP-V2.00-metering.xsd](xsd/UFTP-V2.00-metering.xsd) \ No newline at end of file diff --git a/specifications/2.0.0/xsd/UFTP-V2.00-agr-cro.xsd b/specifications/2.0.0/xsd/UFTP-V2.00-agr-cro.xsd new file mode 100644 index 00000000..7b6209c7 --- /dev/null +++ b/specifications/2.0.0/xsd/UFTP-V2.00-agr-cro.xsd @@ -0,0 +1 @@ + Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. A connection that the AGR want the CRO to update EntityAddress of the Connection entity being updated. The first Period hat the AGR represents the prosumer at this Connection. The last Period that the AGR represents the prosumer at this Connection, if applicable. MessageID of the AGRPortfolioUpdate that has just been accepted or rejected Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. The Period for which the AGR requests the portfolio information. Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. MessageID of the AGRPortfolioQuery that has just been accepted or rejected The Period that the portfolio is valid. EntityAddress of the CongestionPoint. Indicates whether the DSO accepts mutual exclusive FlexOffers on this CongestionPoint. Indicates which party is responsible for day-ahead redispatch. Indicates which party is responsible for intraday ahead redispatch, AGR or DSO. If not specified, there will be no intraday trading on this CongestionPoint. EntityAddress of the Connection. \ No newline at end of file diff --git a/specifications/2.0.0/xsd/UFTP-V2.00-agr-dso.xsd b/specifications/2.0.0/xsd/UFTP-V2.00-agr-dso.xsd new file mode 100644 index 00000000..b75d14bc --- /dev/null +++ b/specifications/2.0.0/xsd/UFTP-V2.00-agr-dso.xsd @@ -0,0 +1 @@ + ISO 8601 time interval (minutes only, for example PT15M) indicating the duration of the ISPs referenced in this message. Although the ISP length is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant ISP duration. Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. Day (in yyyy-mm-dd format) the ISPs referenced in this Flex* message belong to. Entity Address of the Congestion Point this D-Prognosis applies to. The ISP represents one or more Imbalance Settlement Periods and is used by Prognosis and Flex-related messages. Revision of this message. A sequence number that must be incremented each time a new revision of a prognosis is sent. The combination of SenderDomain and PrognosisSequence should be unique Power specified for this ISP in Watts. Also see the important notes about the sign of this attribute in the main documentation entry for the ISP element. Number of the first ISPs this element refers to. The first ISP of a day has number 1. The number of the ISPs this element represents. Optional, default value is 1. MessageID of the D-Prognosis message this request is based on. The ISP represents one or more Imbalance Settlement Periods and is used by Prognosis and Flex-related messages. Reference to the bilateral contract in question. Message reference, assigned by the DSO originating the FlexReservationUpdate. Remaining reserved power specified for this ISP in Watts. Number of the first ISPs this element refers to. The first ISP of a day has number 1. The number of the ISPs this element represents. Optional, default value is 1. MessageID of the FlexReservationUpdate message this request is based on. The ISP represents one or more Imbalance Settlement Periods and is used by Prognosis and Flex-related messages. Revision of this message, a sequence number that must be incremented each time a new revision of a FlexRequest message is sent. Date and time, including the time zone (ISO 8601 formatted as per http://www.w3.org/TR/NOTE-datetime) until which the FlexRequest message is valid. Power specified for this ISP in Watts. Also see the important notes about the sign of this attribute in the main documentation entry for the ISP element. Power specified for this ISP in Watts. Also see the important notes about the sign of this attribute in the main documentation entry for the ISP element. Number of the first ISPs this element refers to. The first ISP of a day has number 1. The number of the ISPs this element represents. Optional, default value is 1. MessageID of the FlexRequest message this request is based on. If the DSO does not support mutually exclusive offers it will reject FlexOffers that contain more than one OfferOption. Date and time, including the time zone (ISO 8601 formatted as per http://www.w3.org/TR/NOTE-datetime) until which the FlexOffer is valid. MessageID of the FlexRequest message this request is based on. Reference to the concerning bilateral contract, if applicable. MessageID of the D-Prognosis this request is based on, if it has been agreed that the baseline is based on D-prognoses. Identification of the baseline prognosis, if another baseline methodology is used than based on D-prognoses ISO 4217 code indicating the currency that applies to the price of the FlexOffer. The ISP represents one or more Imbalance Settlement Periods and is used by Prognosis and Flex-related messages. The identification of this option. The asking price for the flexibility offered in this option. The minimal activation factor for this OfferOption. An AGR may choose to include MinActivationFactor in FlexOffers even if the DSO is not interested in partial activation. In that case the DSO will simply use an ActivationFactor of 1.00 in every FlexOrder. Power specified for this ISP in Watts. Also see the important notes about the sign of this attribute in the main documentation entry for the ISP element. Number of the first ISPs this element refers to. The first ISP of a day has number 1. The number of the ISPs this element represents. Optional, default value is 1. MessageID of the FlexOffer message this request is based on. MessageID of the FlexOffer message that is being revoked: this FlexOffer must have been accepted previously. MessageID of the FlexOfferRevocation message this request is based on. The ISP represents one or more Imbalance Settlement Periods and is used by Prognosis and Flex-related messages. MessageID of the FlexOffer message this order is based on. Reference to the concerning bilateral contract, if applicable. MessageID of the D-Prognosis this request is based on, if it has been agreed that the baseline is based on D-prognoses. Identification of the baseline prognosis, if another baseline methodology is used than based on D-prognoses The price for the flexibility ordered. Usually, the price should match the price of the related FlexOffer. ISO 4217 code indicating the currency that applies to the price of the FlexOffer. Order number assigned by the DSO originating the FlexOrder. To be stored by the AGR and used in the settlement phase. The OptionReference from the OfferOption chosen from the FlexOffer. The activation factor for this OfferOption. The ActivationFactor must be greater than or equal to the MinActivationFactor in the OfferOption chosen from the FlexOffer. Power specified for this ISP in Watts. Also see the important notes about the sign of this attribute in the main documentation entry for the ISP element. Number of the first ISPs this element refers to. The first ISP of a day has number 1. The number of the ISPs this element represents. Optional, default value is 1. MessageID of the FlexOrder that has just been accepted or rejected. First Period of the settlement period this message applies to. Last Period of the settlement period this message applies to. Settlement reference, assigned by the DSO originating the FlexSettlement. ISO 4217 code indicating the currency that applies to all amounts (flex price, penalty and net settlement) in this message. Reference to the concerning bilateral contract, if it is linked to it MessageID of the Prognosis message (more specifically: the D-Prognosis) the FlexOrder is based on, if it has been agreed that the baseline is based on D-prognoses. Identification of the baseline prognosis, if another baseline methodology is used than based on D-prognoses. Entity Address of the Congestion Point the FlexOrder applies to. The price accepted for supplying the ordered amount of flexibility as per the referenced FlexOrder messages. Penalty due a non-zero PowerDeficiency Net settlement amount for this Period: Price minus Penalty. Number of the first ISPs this element refers to. The first ISP of a day has number 1. The number of the ISPs this element represents. Optional, default value is 1. Power originally forecast (as per the referenced baseline) for this ISP in Watts. Amount of flex power ordered (as per the referenced FlexOrder message) for this ISP in Watts. Actual amount of power for this ISP in Watts, as measured/determined by the DSO and allocated to the AGR. Actual amount of flex power delivered for this ISP in Watts, as determined by the DSO. Amount of flex power sold but not delivered for this ISP in Watts, as determined by the DSO. The ISP represents one or more Imbalance Settlement Periods and is used by Prognosis and Flex-related messages. MessageID of the FlexSettlemnet message that has just been accepted or rejected Reference included in the FlexSettlement that has just been received. Order reference assigned by the DSO when originating the FlexOrder. Indication whether the AGR accepts the order settlement details provided by the DSO (and will invoice accordingly), or disputes these details. In case the order settlement was disputed, this attribute must contain a human-readable description of the reason. Reference to the concerning bilateral contract. Period the being settled. Number of the first ISPs this element refers to. The first ISP of a day has number 1. The number of the ISPs this element represents. Optional, default value is 1. Amount of flex power that has been reserved (and not released using a FlexReservationUpdate message). Amount of flex power that has been both reserved in advance and has been requested using a FlexRequest (i.e. the lowest amount of flex power for this ISP). If there was no FlexRequest, this field is omitted. Amount of flex power that is considered available based on the FlexRequest in question. In case RequestedPower=0, AvailablePower is defined so that the offered power is allowed to be between 0 and AvailablePower in terms of compliancy (see Appendix 3 for details). In case RequestedPower ≠0, AvailablePower is defined so that the offered power is allowed to exceed the amount of requested power up to AvailablePower. If this is relevant for settlement, the DSO can include this field. Amount of flex power that has been reserved in advance, requested using a FlexRequest and covered in an offer from the AGR. If there was no offer, this field is omitted. If there were multiple offers, only the one is considered that is most compliant . Amount of flex power that has been ordered using a FlexOrder message that was based on a FlexOffer, both linked to this contract. If there was no order, this field is omitted. \ No newline at end of file diff --git a/specifications/2.0.0/xsd/UFTP-V2.00-agr.xsd b/specifications/2.0.0/xsd/UFTP-V2.00-agr.xsd new file mode 100644 index 00000000..9ad3dee4 --- /dev/null +++ b/specifications/2.0.0/xsd/UFTP-V2.00-agr.xsd @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/specifications/2.0.0/xsd/UFTP-V2.00-common.xsd b/specifications/2.0.0/xsd/UFTP-V2.00-common.xsd new file mode 100644 index 00000000..c26c7c6c --- /dev/null +++ b/specifications/2.0.0/xsd/UFTP-V2.00-common.xsd @@ -0,0 +1 @@ + The SignedMessage element represents the secure wrapper used to submit USEF XML messages from the local message queue to the message queue of a remote participant. It contains minimal metadata (which is distinct from the common metadata used for all other messages), allowing the recipient to look up the sender's cryptographic scheme and public keys, and the actual XML message, as transformed (signed/sealed) using that cryptographic scheme. The Internet domain of the USEF participant sending this message. Upon receiving a message, the recipient should validate that its value matches the corresponding attribute value specified in the inner XML message, once un-sealed: if not, the message must be rejected as invalid. The USEF role of the participant sending this message: AGR, BRP, CRO, DSO or MDC. Receive-time validation should take place as described for the SenderDomain attribute above. The Base-64 encoded inner XML message contained in this wrapper, as transformed (signed/sealed) using the sender's cryptographic scheme. The recipient can determine which scheme applies using a DNS or configuration file lookup, based on the combination of SenderDomain and SenderRole. The Internet domain of the USEF participant sending this message. When receiving a message, its value should match the value specified in the SignedMessage wrapper: otherwise, the message must be rejected as invalid. When replying to this message, this attribute is used to look up the USEF endpoint the reply message should be delivered to. Internet domain of the participant this message is intended for. When sending a message, this attribute, combined with the RecipientRole, is used to look up the USEF endpoint the message should be delivered to. Date and time this message was created, including the time zone (ISO 8601 formatted as per http://www.w3.org/TR/NOTE-datetime). Unique identifier (UUID/GUID as per IETF RFC 4122) for this message, to be generated when composing each message. Unique identifier (UUID/GUID as per IETF RFC 4122) used to correlate responses with requests, to be generated when composing the first message in a conversation and subsequently copied from the original message to each reply message. Indication whether the query was executed successfully or failed. In case the query failed, this attribute must contain a human-readable description of the failure reason. \ No newline at end of file diff --git a/specifications/2.0.0/xsd/UFTP-V2.00-cro-dso.xsd b/specifications/2.0.0/xsd/UFTP-V2.00-cro-dso.xsd new file mode 100644 index 00000000..41d3c934 --- /dev/null +++ b/specifications/2.0.0/xsd/UFTP-V2.00-cro-dso.xsd @@ -0,0 +1 @@ + Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. A congestion point that the DSO wants the CRO to update EntityAddress of the Connection. The first Period that the Connection is part of this CongestionPoint. The last Period that the Connection is part of this CongestionPoint. Indicates whether the DSO accepts mutual exclusive FlexOffers on this CongestionPoint. Indicates which party is responsible for day-ahead redispatch. Indicates which party is responsible for intraday ahead redispatch, AGR or DSO. If not specified, there will be no intraday trading on this CongestionPoint. A connection that the DSO wants the CRO to update EntityAddress of the Connection. The first Period that the Connection is part of this CongestionPoint. The last Period that the Connection is part of this CongestionPoint. MessageID of the DSOPortfolioUpdateResponse that has just been accepted or rejected Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. The Period for which the AGR requests the portfolio information. EntityAddress of the CongestionPoint MessageID of the AGRPortfolioQuery that has just been accepted or rejected Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. The Period for which the AGR requests the portfolio information. EntityAddress of the Connection. A Connection that is part of the congestion point. EntityAddress of the Connection. The internet domain of the AGR that represents the prosumer connected on this Connection, if applicable. \ No newline at end of file diff --git a/specifications/2.0.0/xsd/UFTP-V2.00-cro.xsd b/specifications/2.0.0/xsd/UFTP-V2.00-cro.xsd new file mode 100644 index 00000000..4466e821 --- /dev/null +++ b/specifications/2.0.0/xsd/UFTP-V2.00-cro.xsd @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/specifications/2.0.0/xsd/UFTP-V2.00-dso.xsd b/specifications/2.0.0/xsd/UFTP-V2.00-dso.xsd new file mode 100644 index 00000000..57b72ef0 --- /dev/null +++ b/specifications/2.0.0/xsd/UFTP-V2.00-dso.xsd @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/specifications/2.0.0/xsd/UFTP-V2.00-metering.xsd b/specifications/2.0.0/xsd/UFTP-V2.00-metering.xsd new file mode 100644 index 00000000..565a1d42 --- /dev/null +++ b/specifications/2.0.0/xsd/UFTP-V2.00-metering.xsd @@ -0,0 +1,151 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Imported energy, consumed during the ISP + + + + + Exported energy, generated during the ISP + + + + + Cumulative metered imported energy reading, at the end of the ISP + + + + + Cumulative metered exported energy reading, at the end of the ISP + + + + + Import tariff rate for a given ISP + + + + + Export tariff rate for a given ISP + + + + + + + + + + + + + The message must contain one or more profiles with metering, energy or price values. + + + + + + ISO 8601 time interval (minutes only, for example PT15M) indicating the duration of the ISPs referenced in this message. Although the ISP length is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant ISP duration. + + + + + Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. + + + + + ISO 4217 code indicating the currency that applies to the price of the Tariff Rates. Only required if ImportTariff or ExportTariff profiles are included. + + + + + Day (in yyyy-mm-dd format) the ISPs referenced in this Metering message belong to. + + + + + EAN of the meter the message applies to. + + + + + + + + + + + A profile carries a sequence of ISPs with a defined type of metering data + + + + + + + + + + + + + + Number of the ISP this element refers to. The first ISP of a day has number 1. + + + + + Metering, energy or price value at the end of this ISP, in the designated profile units. + + + + + + + + + + + + MessageID of the Metering message this response is based on. + + + + + + + + + \ No newline at end of file diff --git a/specifications/3.0.0/README.md b/specifications/3.0.0/README.md new file mode 100644 index 00000000..f540436e --- /dev/null +++ b/specifications/3.0.0/README.md @@ -0,0 +1,11 @@ +# Shapeshifter Specification 3.0.0 + +This directory preserves the XSD snapshot defined by the `V3.0.0` Git tag. + +Source tag: [`V3.0.0`](https://github.com/shapeshifter/shapeshifter-specification/tree/V3.0.0) at commit `2b2f8f394eeab7a47f14e31593bd6634f37621bc`. + +The `docs/` Markdown and image snapshot is from [commit `24da5e2`](https://github.com/shapeshifter/shapeshifter-specification/commit/24da5e2d8443108a23aaceca8a8215330fb0c65b), the first complete reviewed Markdown conversion. The Git tag predates that conversion; this documentation snapshot represents the v3.0.0 specification, not files present in the tag tree. + +`docs/versions.md` is a shared migration index added after the historical snapshot to support the version selector and artifact downloads. + +The original XSD filenames, schema references, Markdown paths, and image references are retained. Do not edit this snapshot; make specification changes in the development sources and publish them as a new version. \ No newline at end of file diff --git a/specifications/3.0.0/USEF Flex Trading Protocol Specifications 3.0.0.docx b/specifications/3.0.0/USEF Flex Trading Protocol Specifications 3.0.0.docx new file mode 100644 index 00000000..f7696cd1 Binary files /dev/null and b/specifications/3.0.0/USEF Flex Trading Protocol Specifications 3.0.0.docx differ diff --git a/specifications/3.0.0/USEF Flex Trading Protocol Specifications 3.0.0.pdf b/specifications/3.0.0/USEF Flex Trading Protocol Specifications 3.0.0.pdf new file mode 100644 index 00000000..f2f8518c Binary files /dev/null and b/specifications/3.0.0/USEF Flex Trading Protocol Specifications 3.0.0.pdf differ diff --git a/docs/about/levels-of-compliancy.md b/specifications/3.0.0/docs/about/levels-of-compliancy.md similarity index 100% rename from docs/about/levels-of-compliancy.md rename to specifications/3.0.0/docs/about/levels-of-compliancy.md diff --git a/docs/about/purpose.md b/specifications/3.0.0/docs/about/purpose.md similarity index 100% rename from docs/about/purpose.md rename to specifications/3.0.0/docs/about/purpose.md diff --git a/docs/about/reading-guideline.md b/specifications/3.0.0/docs/about/reading-guideline.md similarity index 100% rename from docs/about/reading-guideline.md rename to specifications/3.0.0/docs/about/reading-guideline.md diff --git a/specifications/3.0.0/docs/about/scope.md b/specifications/3.0.0/docs/about/scope.md new file mode 100644 index 00000000..d1e3d6d6 --- /dev/null +++ b/specifications/3.0.0/docs/about/scope.md @@ -0,0 +1,68 @@ + + +# Scope + +## Constraint management services + +Constraint management services help grid operators (TSOs and DSOs) to optimize grid operation according to physical and market constraints. +USEF [^B1] distinguishes four different flexibility services within the constraint management category: grid capacity management, congestion management, voltage control and controlled islanding. +UFTP can be used for the first two of these. + +[^B1]: USEF, "Flexibility Value Chain (update 2018)," 8 10 2018. [Online]. Available: [https://www.usef.energy/app/uploads/2018/11/USEF-White-paper-Flexibility-Value-Chain-2018-version-1.0_Oct18.pdf](https://www.usef.energy/app/uploads/2018/11/USEF-White-paper-Flexibility-Value-Chain-2018-version-1.0_Oct18.pdf). + +### Grid capacity management + +Grid capacity management refers to the use of explicit demand-side flexibility (by the DSO or TSO) to increase operational efficiency without impacting freedom of dispatch, trade and connect (copper plate principle). +It is primarily used to defer grid reinforcements, optimize asset operational performance, reduce grid losses, or support planned maintenance. +The implication is that AGRs (and prosumers) participate in the product on a voluntary basis; i. +e. +motivated by appropriate financial incentives. + +### Congestion management + +Congestion management refers to the use of flexibility to reduce peak loads, in order to avoid system overload and the associated component or system failures. +Contrary to grid capacity management, it will typically limit freedom of dispatch, trade and/or connect. +It is primarily used in unanticipated overload situations; e. +g. +those which could not be forecast during long-term grid planning processes, or where load/ generation increases have outpaced grid reinforcement efforts. +Congestion management is a temporary solution (typically until grid reinforcement takes place) and is a highly-regulated mechanism. +At present, it is only available to TSOs in most European member states although it may be offered to DSOs in the future. + +The two mechanisms differ in the freedom of dispatch, trade and/or connect and this is handled via contracts and will have impact on the settlement components. + +## Bilateral trading and trading via a market platform + +![](../assets/images/image3.emf.odg.svg) + +UFTP is designed for bilateral trading between the AGR and DSO. +Trading via market platforms can bring added value, see [^B2]. +In UFTP, market platforms may take the role of trading counterparty, hence serving as a DSO proxy in trades with the AGR, and as an AGR proxy in trades with the DSO. +When trading via a platform, the role of FlexRequests from DSOs to AGRs is less obvious; i.e., a DSO has free choice of the available FlexOffers. +In addition, FlexOffers and FlexRequests do not need to be directly related and so UFTP supports unsolicited FlexOffers without requiring a reference to an underlying FlexRequest. + +## TSO/DSO coordination + +![](../assets/images/image4.emf.odg.svg) + +USEF assumes that a DSO or TSO can freely and independently trade flexibility with AGRs. +Any potential goal conflicts can be settled through the market mechanism. +Alternatively, TSO and DSO requests can be aligned, resulting in a TSO/DSO coordination platform where TSOs and DSOs coordinate the tendering, trading, activation and/or settlement of flexibility for their own purposes ( i. e. ancillary services). +See [^B2] for a discussion on this topic. + +[^B2]: USEF, "White paper: Flexibility Platforms," 2 november 2018. [Online]. Available: [https://www.usef.energy/app/uploads/2018/11/USEF-White-Paper-Flexibility-Platforms-version-1.0_Nov2018.pdf](https://www.usef.energy/app/uploads/2018/11/USEF-White-Paper-Flexibility-Platforms-version-1.0_Nov2018.pdf). + +UFTP can be applied without any further changes in a configuration where there is TSO/DSO coordination. + +## Alternative use + +The text, graphs and examples in this document assume flex trading between AGR and DSO. +However, UFTP can equally be used for grid constraint services between an AGR and TSO. + +The messages defined in UFTP can also be used for flexibility trading in the plan phase between an AGR and BRP. +See the USEF Framework Specifications [^B3] for a complete description of this alternative use. + +[^B3]: USEF, "USEF - The FrameWork Specifications 2015," 2015. [Online]. diff --git a/docs/appendix/bibliography.md b/specifications/3.0.0/docs/appendix/bibliography.md similarity index 100% rename from docs/appendix/bibliography.md rename to specifications/3.0.0/docs/appendix/bibliography.md diff --git a/specifications/3.0.0/docs/appendix/flex-reservation-mechanism.md b/specifications/3.0.0/docs/appendix/flex-reservation-mechanism.md new file mode 100644 index 00000000..be502fef --- /dev/null +++ b/specifications/3.0.0/docs/appendix/flex-reservation-mechanism.md @@ -0,0 +1,44 @@ + + +# Flex reservation mechanism + +As introduced in [Bilateral contract: FlexOption](../general-description/contract-phase.md#bilateral-contract-flexoption), DSO’s may want to contract a minimum amount of flexibility to be sure that it is available on request. +The FlexOption (not part of UFTP) is a bilateral contract between DSO and AGR to reserve a specified amount of flexibility at a specific location (i.e. congestion point), for a specified time schedule and duration. +In the day-ahead grid planning process, the DSO’s forecast will indicate whether the contracted amount of flexibility is actually needed. +If not, the flexibility can be used for other purposes. +The DSO can send a FlexReservationUpdate message to signal the actual needs to the AGR. +This appendix describes the purpose of this FlexReservationUpdate message and its impact on the contractual obligations and the actual FlexRequest that may follow in the validate phase. + +
+ ![Example flex reservation and FlexReservationUpdate, displayed in graphs](../assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg){ width=1000px } +
Example flex reservation and FlexReservationUpdate, displayed in graphs
+
+ +The figure above illustrates how ISPs 11 to 16 are part of a contract, where the AGR is required to reserve flexibility at ISPs 12 to 15 (downwards power only – for more information on direction and amount of power, see Section [Power](../message-descriptions/message-catalog/power.md)). +The DSO was obliged to send a FlexReservationUpdate before each deadline, confirming the reserved power or partially releasing it. +The power values from the updated reservation should always be equal to, or lower than, the (absolute) values from the original reservation but since the contract is out-of-scope for UFTP, the DSO and AGR should maintain their own agreements about this. + +After the FlexReservationUpdate, the AGR is obliged to keep the amount of flexibility available – even if no FlexRequest follows. +After a FlexRequest is published, the AGR is obliged to produce a FlexOffer that meets the contract within the boundaries of the FlexRequest, where only the lowest reserved and requested power is valid for the contract. +This is illustrated in the following figure: + +
+ ![Example FlexRequest and requirements of FlexOffer, displayed in graphs](../assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg){ width=1000px } +
Example FlexRequest and requirements of FlexOffer, displayed in graphs
+
+ +For further information on the FlexRequest, see [Flexibility trading between the AGR and DSO](../general-description/validate-phase.md#flexibility-trading-between-the-agr-and-dso). +Both the FlexReservationUpdate and the FlexRequest can only reduce the amount of power that the AGR is obliged to offer, as opposed to increase it. +For ISP 12, the requested power exceeds the power that the AGR had to reserve in advance. +The contract is therefore only valid for the lowest (absolute) power value, being -2. +For ISP 14, the opposite is happening: the reserved power is not requested. +Therefore, the AGR is not obliged to provide flexibility for ISP 14. + +For ISP 15 and 16, available space is given for the AGR to deviate in the opposite direction. +**For all ISPs that are included in the contract – even when the reservation is set to 0 – the AGR is obliged to conform to the restrictions given by the FlexRequest, including the bounds of available space.** +The AGR is also free to provide more power than agreed, as long as it contributes to the decrease in congestion. +In this example, the resulting FlexOffer that complies to the contract must be as illustrated in the graph on the right in the figure above. diff --git a/specifications/3.0.0/docs/appendix/glossary.md b/specifications/3.0.0/docs/appendix/glossary.md new file mode 100644 index 00000000..990abd35 --- /dev/null +++ b/specifications/3.0.0/docs/appendix/glossary.md @@ -0,0 +1,37 @@ + + +# Glossary + +| | | +|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------| +| A-plan | Aggregator-plan, used as Aggregator’s nomination | +| AGR | Aggregator. Role whose goal it is to maximize the value of flexibility, taking into account customer needs, economical optimization and grid capacity. | +| BRP | Balance Responsible Party | +| C&I | Commercial & Industry | +| Common Reference | Information about the Energy grid and the involved parties, which needs to be unambiguously available to all participating parties. | +| Congestion Point | Point in de grid where the grid capacity is not always sufficient to distribute the requested amount of energy | +| CRO | Common Reference Operator | +| D-prognosis | Prognosis regarding the Distribution of energy | +| DNO | Distribution Network Operator | +| DSO | Distribution System Operator | +| E-program | Energy Program – aggregated (daily) energy transactions of a BRP to be provided to the TSO | +| FlexOffer | Flexibility Offer, response to a Flexibility Request | +| FlexOrder | Flexibility Order, a response to a Flexibility Offer | +| FlexRequest | Flexibility Request | +| Grid | Network for the transport and distribution of energy | +| ISP | Imbalance Settlement Period | +| MBMA | Measure Before Measure After (baseline methodology) | +| MCM | Market-based Coordination Mechanism (USEF) | +| MDC | Meter Data Company | +| P&S | Privacy & Security | +| Prosumer | A consumer which is capable of producing energy as well | +| Settlement | Determining the energy production and consumption and used flexibility as preparation for the billing process. | +| Supplier | Has a contractual relationship with Prosumers to source, supply and invoice energy | +| TSO | Transmission System Operator | +| UFTP | USEF Flex Trading Protocol | +| USEF | Universal Smart Energy Framework | + diff --git a/specifications/3.0.0/docs/appendix/message-transport-mechanism.md b/specifications/3.0.0/docs/appendix/message-transport-mechanism.md new file mode 100644 index 00000000..e6b52b81 --- /dev/null +++ b/specifications/3.0.0/docs/appendix/message-transport-mechanism.md @@ -0,0 +1,265 @@ + + +# Message transport mechanism + +When implementing the USEF best-practice message transfer mechanism, the procedures outlined in this section apply. + +## Cryptographic Scheme (CS) + +The USEF privacy and security guidelines require all participants to be able to securely transmit and authenticate messages. +For these purposes, a transport-independent cryptographic scheme is specified, identified as Cryptographic Scheme Type 1 (CS1): implementation is a recommended practice for all implementations[^13]. +Based on NaCl[^14], a public domain library with high-speed state-of-the-art security features and a purpose-built and straightforward programming interface[^15], this scheme requires participants to generate two public/private key pairs: + +[^13]: If this recommendation is not followed, a compatible implementation should be provided in order to achieve USEF compliance. + +[^14]: + Pronounced “salt” and available with extensive documentation from [http://nacl.cr.yp.to/](http://nacl.cr.yp.to/). + Sodium, [https://github.com/jedisct1/libsodium](https://github.com/jedisct1/libsodium), is an extended NaCl derivative with Windows, OS X and Linux platform support and many available language bindings. + Sodium is highly recommended for USEF-compliant implementations. + +[^15]: Whereas typical cryptographic libraries require several steps to implement message encryption or signing, with each step opening the door for fatal programming mistakes, NaCl offers simple high-level functions which take care of everything, dramatically reducing the risk of inadvertent implementation errors. + +| Purpose | NaCl function | Private key bits | Public key bits | +|----------------------------------|---------------------|------------------|-----------------| +| Digital signatures | crypto_sign_keypair | 512 | 256 | +| Authenticated message encryption | crypto_box_keypair | 256 | 256 | + +The resulting private keys must be securely stored using an operating system or language-supplied facility for that specific purpose (e.g. the Win32 Data Protection API, OS X Keychain service or JVM KeyStore). +In addition to being stored locally, the public keys are exchanged with other USEF participants. +For that purpose, the keys are joined together in a single 64-byte array (signature key followed by encryption key), Base-64 encoded and prefixed by the constant cs1 and a period (indicating that the version 1 cryptographic scheme is used). +For example: `cs1.V4lZrkYHq8FzneXxUML+QEMXMul3tBm+gPGoVDIZBA92VoWTu8/kRu2Zx72XOm1i/qwwoSgXjqSAqSa43myCaQ==` + +This public key string can be published in the DNS zone of the domain used in the associated entity address, or manually exchanged with other USEF participants. +If DNS is used, implementation of DNSSEC is mandatory, as otherwise the key material would be completely untrusted. +Implementations must use a DNSSEC validating resolver, which can either be built-in, or an external resolver on a fully trusted network. + +When signing an outgoing message using the private digital signature key and NaCl’s `crypto_sign` function, the result is an opaque blob: the sealed message. +Unsealing this message, using the corresponding public digital signature key and `crypto_sign_open`, performs signature verification and returns the message plaintext. +Since this all happens in the same API call, it is not possible to accidentally process an unsigned or incorrectly signed message. + +### Message exchange logic + +The entire message exchange, from the client’s outgoing message queue to the server’s incoming message queue, using HTTP-over-TLS transport and the default cryptographic scheme, is visualized in detail in the picture below. + +
+ ![End-to-end USEF message exchange.](../assets/images/image23.emf.odg.svg){ width=1000px } +
End-to-end USEF message exchange.
+
+ +Messages go through the following stages between retrieval from the client’s outgoing message queue and delivery to the server’s inbound message queue: + +## Service discovery + +### Versioning + +For versioning of the specification we use semantic versioning (see [https://semver.org/](https://semver.org/)). +In short: MAJOR.MINOR.PATCH. Each new major version is incompatible with previous versions; New minor versions are backwards compatible with previous minor versions within the same major version. + +### Supporting multiple versions of the protocol + +DSO’s should be more flexible than AGR’s, so DSO’s will support multiple versions of the protocol, but only for a restricted time. + +Also, the CRO should support multiple versions. + +DSO's and CRO are expected to support at most the three latest versions. + +### Version coupled to URL + +Each major version should have a different url-path, so it is possible to route each incompatible protocol version to another service. +This means that for minor changes and patches the url will remain the same. +The convention for the url-path (by example) is as follows: + +version 2.0.0: /shapeshifter/api/v2/message + +version 2.1.0: /shapeshifter/api/v2/message + +version 3.0.1: /shapeshifter/api/v3/message + +### Messages + +The metadata of each message contains the specification version. +A rejection reason will be added to reject a message with an invalid version + +### Service discovery + +In the service discovery stage, DNS[^16] is used to discover the capabilities as well as the endpoint host name and IP address of the remote participant. +Assuming the Internet domain name of the remote participant is example.com, the relevant DNS records are as follows: + +[^16]: + Each USEF participant is responsible for publishing its own endpoint and public key information in a self-managed DNS zone. + To prevent man-in-the-middle interference with the published information, use of DNSSEC is mandatory for such zones. + +| | | +|----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| _usef.example.com | TXT record specifying the version of the USEF specification implemented by this participant, e.g. `2015` | +| \__role_._usef.example.com | TXT record containing up to two[^17] space-separated Base-64 encoded public key strings for the specified role, where role is one of the values `AGR`, `CRO` or `DSO`. This data is only queried if (part of) the outgoing message needs to be encrypted | +| _http.\_*role*._usef.example.com | CNAME record indicating the HTTP endpoint receiving messages for the specified role.
This label must not have any resource records of other types (with the exception of the mandatory DNSSEC-related records[^18]) and the alias should resolve to an A or AAAA record[^19].
On the endpoint host, the implementation must listen on the well-known IANA-assigned TCP port for HTTP-over-TLS, i.e. 443.
The implementation may listen on port 80 as well, but only for purposes such as supporting the HTTP/2 connection upgrade mechanism and never for unencrypted message exchange. | + +[^17]: Usually one public key string will be present, but in order to support key rotation without invalidating in-transit messages, the implementation should list both the old and the new key for a short period of time (e.g. 24 hours) after a key has been replaced + +[^18]: + USEF participants must enable DNSSEC and implementations must use a validating resolver, treating verification failures as temporary errors, eligible for retrying later. + Absent DNSSEC authentication, private key strings must not be relied on, and separate manual secure key exchange is required. + +[^19]: + As per IETF RFC 1034 [^B14], implementations must not fail when presented with CNAME chains or loops. + Chains should be followed (to an implementation-defined maximum depth) and any loops or errors treated as temporary. + +[^B14]: P. Mockapetris, ""Domain names - concepts and facilities", STD 13, RFC 1034," 1987. + +The message will remain in the service discovery stage until all required data is available, or a participant-configurable and possibly message-class specific timeout timer expires. +A DNS reply must have the NOERROR status, as well as syntactically valid and DNSSEC-authenticated content, in order to be considered usable. +Other status codes such as SERVFAIL/NXDOMAIN, as well as connection failures or invalid record contents are considered temporary errors, in which case the lookup will be retried later within the timeout period. + +To prevent transient Internet connectivity or participant configuration issues from inhibiting message exchange, the timer value used for such a period should be at least one hour for routine messages. +If service discovery fails due to inability to collect all required data within this timeout period, the delivery of the message fails. +Such messages are removed from the outgoing queue and returned to the sending process, indicating a transport error. +Note that, although message queue implementations may inform the sending process about delivery delays, only the final success or failure status is authoritative. +When retrying failed requests, the implementation must implement an exponential back off mechanism to prevent undue load on the remote service. +The implementation should set a reasonable maximum delay interval based on local factors, such as network capacity. + +For test situations or small-scale deployments where service discovery via DNS is too cumbersome, or requires unreasonable amounts of additional work, participants should be able to specify service information in a local configuration file. +Since activities on the energy market are most likely regulated by national oversight bodies, and such organizations are natural candidates for running the authoritative DNS zone for accredited market participants, implementations are encouraged to support a list of DNS suffixes that correspond to the zones maintained by such regulators, and to automatically query these zones. +For example, if an energy.authority.test is on the DNS suffix list, this zone is queried for _usef.example.com.energy.authority.test in order to determine if example.com is an authorized market participant. + +
+ ![Example of the DNS relationships between a single USEF endpoint and multiple zones](../assets/images/image24.svg){ width=1000px } +
Example of the DNS relationships between a single USEF endpoint and multiple zones
+
+ +An example of an anticipated DNS setup is shown above. Here, an incumbent DSO (using the Internet domain `DSO.example`) operates a USEF endpoint, named `SSL.DSO.example`. +The DNS entries for the USEF DSO and CRO role processes that underpin the DSO’s core business both refer to this endpoint, ultimately leading to an IP/port combination usable for submitting USEF messages to. + +In order to offer differentiated services to various customer segments, the DSO has also set up various AGRs, each operating its own web site and Internet domain. +One of these AGRs is shown in the diagram. +Instead of operating its own USEF endpoint, this AGR delegates this responsibility to its parent company, by pointing its USEF DNS records at the `SSL.DSO.example` endpoint. + +The second AGR shown in the diagram is an independent market participant but lacks sufficient scale to warrant running its own USEF endpoint. +Instead, it outsources that task to the DSO. +Note that, due to the sensitive data included in some USEF messages, strong contractual and technological safeguards (such as full-message encryption) are required to correctly apply the USEF privacy and security guidelines. +Using a single USEF endpoint as shown here has a number of advantages, mostly related to the fact that only a single SSL certificate and IP address are required to operate the endpoint. +Requiring unique instances of these would be complex and expensive, especially if the DSO runs tens or even hundreds of segment-specific AGRs. + +There are, of course, disadvantages as well. +Unless network-level measures are taken to prevent this, a single endpoint also means a single point of failure, and shared hosting scenarios that do not ultimately involve only a single legal entity require special attention to the protection of message contents. + +## Transmission + +Once a valid service endpoint is available, the message enters the transmission stage[^20]. +The implementation will now, for a reasonable amount of time (which is again at least one hour for routine messages, employing exponential back off), attempt to deliver the message to the remote participant. + +[^20]: For messages containing non-public information, this stage transition may also include encryption of message sections using the public encryption key of the remote participant. + +Messages are sent using a HTTP POST operation with the text/xml[^21] content type, the UTF8 character set and content-length indication. +The request URI depends on the USEF implementation level and host name listed in DNS by the recipient. +For USEF 2019 and the host `example.com`, it will be [https://example.com/USEF/2019/SignedMessage](https://example.com/USEF/2019/SignedMessage). + +[^21]: + The USEF specification uses XML, since this format is already widely used in the rather conservative energy market, and enjoys wide and mature tooling support (particularly in the area of schema authoring and validation). + Unlike other XML-based initiatives (such as WS-*), lightweight implementations are considered key, and alternate serialization formats (such as JSON) should be viable as well, despite being out of scope of this specification. + If any such alternate message formats are implemented, fallback to XML must be provided as needed, or such implementations will not be USEF-compliant. + +Message content consists of a simple wrapper message, specified as SignedMessage in the USEF XML XSD, available for download from the public USEF web site[^22] at [https://usef.info/schema/2019and](https://usef.info/schema/2019and) documented in section [Message catalog](../message-descriptions/message-catalog/index.md). +All usual protocol conventions should be followed during this stage. +For example, when using HTTP version 1.1, redirects (responses with status code 3xx) should be honored in order to support load balancing. +Any server errors (responses with status code 5xx), unknown response status codes, and connection timeouts and resets should be considered temporary failures and delivery should be re-attempted later within the timeout period. +Only client success or failure messages (responses with status code 200 or a non-ambiguous[^23] 4xx status code, respectively) should be considered final. +This is standard HTTP 1.1 behavior, as fully described in IETF RFC 2616 [^B7]. + +[^B7]: Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, ""Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616," 1999. + +[^22]: Please note that USEF makes no warranties whatsoever as to the uninterrupted availability of its web site, and that production services should not rely on the schema being hosted at this location for purposes such as validation: a local copy should be used instead. + +[^23]: The prime example of an ambiguous HTTP status code is 404 Not Found: since this is commonly returned by front-end servers in case of temporary back-end issues, USEF implementations are encouraged to consider this a temporary error.: + +## Error handling + +In the transmission stage, the guidelines for error handling are as follows: + +Until the point that the message has been successfully validated against the USEF XML schema, errors are communicated using transport protocol mechanisms, e.g. HTTP status codes. +For the HTTP protocol, the following error conditions are common (note that, depending on the server and libraries used, some of these may be handled automatically): + +| Condition | Status code | Error type | +|-----------------------------------------------------------------------------------------------------------------------|----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Missing Content-Length header | 411 Length Required | Permanent (E cannot be resolved without changes to the sending implementation) | +| Invalid Content-Type header (not text/xml) or character set (default: utf-8) | 400 Bad Request | Permanent | +| Originating IP address is sending messages at a rate exceeding receiver policy | 429 Too Many Requests | Temporary | +| Body XML cannot be parsed or is not compliant with USEF XML schema | 400 Bad Request | Permanent | +| Failed to look up the sender’s public signature key in DNS | 419 Authentication Timeout | Temporary (message can be processed when DNS is corrected/replicated) | +| Invalid signature (inner XML message cannot be unsealed, for example due to NaCl’s crypto_sign_open function failing) | 401 Unauthorized | Permanent (since no authorization schemes that would allow the request to be resubmitted are available, unless private arrangements between sender and recipient exist) | +| Unsealed body XML cannot be parsed or is not compliant with the USEF XML schema | 400 Bad Request | Permanent | + +Once a message has been determined to be valid USEF XML, errors are reported using a USEF XML response message with a successful transport disposition (e.g. HTTP status code 200 OK). Possible results in this stage are: + +As in the service discovery stage, messages for which transmission permanently fails are removed from the outgoing queue and returned to the sending process, indicating a transport error. + +### Common Message Metadata + +The USEF XML message obtained after successfully verifying the signature will have a root node corresponding to its message type, which must contain Metadata attributes common to all messages used by the implementation to process the message. +The metadata attributes are defined in [metadata attributes](../message-descriptions/message-catalog/metadata-attributes.md). + +## Awaiting reply + +If message transmission succeeds, the implementation starts waiting for a reply from the remote service. +Although replies to some messages can be expected immediately, other USEF messages may only elicit a response several hours later. +In any case, responses are always decoupled from requests and implementations should be strictly asynchronous, correlating requests and responses using their conversation identifier. + +Because of the asynchronous nature of message exchange, a process needs to be in place for handling messages that do not receive a (timely) reply. +When preparing a new message, the implementation should specify the message class, as well as the time period within which a reply is expected. +The following message classes are defined: + +Incoming replies are validated using the steps outlined in the transmission stage. +Where a reply is rejected, the pending outgoing message remains in the awaiting reply stage until it expires, and any additional manual processing is completed. +Messages for which, ultimately, no reply is received are returned to the sending process, indicating expiry. + +## Service process message error handling + +Since the message exchange process is responsible for transparently handling most, if not all, transient error conditions, service processes have no need for routine error recovery. +In fact, any transport errors reported to the service layer are of such a severe nature that they most likely cannot be corrected without implementation or configuration changes: + +- Malformed messages +- Entity address or signing key misconfigurationsExpired message, despite following manual recovery procedures for non-routine messages (for routine messages, no recovery is required by design but logging may definitely be appropriate) + +The suggested error handling strategy for service processes is to mark the affected remote participant (i.e. not try to exchange any future messages with it) and to emit a diagnostic message indicating that manual intervention is required. +After the issue is investigated and resolved, the configuration can be manually updated to re-enable the participant. + +## EA1 addressing scheme + +In USEF messages, there is often a requirement for a globally unique identity for certain entities. +To meet this requirement, USEF defines the Entity Address (EA). +Each EA consists of a prefix, indicating the addressing scheme, followed by the actual address. +Currently, two addressing schemes are supported: + +- The European Article Number (EAN), commonly used to uniquely identify connection points in the electricity network and therefore a natural identifier to do the same in USEF. +An example of an EA using this scheme is: ean.871685900012636543 +- The USEF type 1 entity address (EA1) is designed to allow participants to generate unique identifiers for themselves and entities managed by them, without relying on a central authority. + +The USEF type 1 EA is structured analogous to the iSCSI IQN. +Paraphrasing IETF RFCs 3720 and 3271 [^B8]: the EA does not define any new naming authorities but uses Internet domain names to ensure global uniqueness. +Furthermore, the EA is constructed to give an organizational naming authority the flexibility to further subdivide the responsibility for name creation to subordinate naming authorities. + +[^B8]: Bakke, M., Hafner, J., Hufferd, J., Voruganti, K., and M. Krueger, ""Internet Small Computer Systems Interface (iSCSI) Naming and Discovery", RFC 3721," 2004. + +This makes the EA format slightly unwieldy but since bandwidth and storage space are not expected to be significant constraints in any USEF implementation, this is considered to be an acceptable tradeoff for not requiring a central authority. +Syntactically, an EA is a variable-length, 7-bit printable ASCII text string containing up to 255 characters. +For example: + +``` +ea1.2013-11.info.usef.test:001:002.090807002a&b# + <- naming authority -> < unique identifier > +``` + +Mostly taken from IETF RFC 3720 [^B9], below are the semantics of the various parts of this EA: + +[^B9]: Satran, J., Meth, K., Sapuntzakis, C., Chadalapaka, M., and E. Zeidner, ""Internet Small Computer Systems Interface (iSCSI)", RFC 3720," 2004. + +| | | +|---------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **ea1** | Constant, indicating this is a type 1 USEF entity address | +| **2013-11** | A date code, in yyyy-mm format. This date must be a date during which the naming authority owned the domain name used in this format, and should be the first month in which the domain name was owned by this naming authority at 00:01 GMT of the first day of the month. This date code uses the Gregorian calendar. All four digits in the year must be present. Both digits of the month must be present, with January == "01" and December == "12". The dash must be included. | +| **info.usef.test** | The reversed domain name of the naming authority (person or organization) creating this entity address | +| **001:002.090807002a&b#** | A locally unique string, which may contain product types, serial numbers, host identifiers, or software keys (specifically: it may include colons to separate organization boundaries). With the exception of the colon prefix, the owner of the domain name can assign everything after the reversed domain name as desired. It is the responsibility of the entity that is the naming authority to ensure that the names it assigns are worldwide unique. | diff --git a/docs/appendix/rationale-for-information-exchange-in-flexibility-request.md b/specifications/3.0.0/docs/appendix/rationale-for-information-exchange-in-flexibility-request.md similarity index 100% rename from docs/appendix/rationale-for-information-exchange-in-flexibility-request.md rename to specifications/3.0.0/docs/appendix/rationale-for-information-exchange-in-flexibility-request.md diff --git a/docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg b/specifications/3.0.0/docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg similarity index 100% rename from docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg rename to specifications/3.0.0/docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg diff --git a/docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg.license b/specifications/3.0.0/docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg.license similarity index 100% rename from docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg.license rename to specifications/3.0.0/docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg.license diff --git a/docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg b/specifications/3.0.0/docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg similarity index 100% rename from docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg rename to specifications/3.0.0/docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg diff --git a/docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg.license b/specifications/3.0.0/docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg.license similarity index 100% rename from docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg.license rename to specifications/3.0.0/docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg.license diff --git a/docs/assets/images/image1.png b/specifications/3.0.0/docs/assets/images/image1.png similarity index 100% rename from docs/assets/images/image1.png rename to specifications/3.0.0/docs/assets/images/image1.png diff --git a/docs/assets/images/image1.png.license b/specifications/3.0.0/docs/assets/images/image1.png.license similarity index 100% rename from docs/assets/images/image1.png.license rename to specifications/3.0.0/docs/assets/images/image1.png.license diff --git a/specifications/3.0.0/docs/assets/images/image10.emf b/specifications/3.0.0/docs/assets/images/image10.emf new file mode 100644 index 00000000..4caeabbe Binary files /dev/null and b/specifications/3.0.0/docs/assets/images/image10.emf differ diff --git a/docs/assets/images/image13.emf.license b/specifications/3.0.0/docs/assets/images/image10.emf.license similarity index 100% rename from docs/assets/images/image13.emf.license rename to specifications/3.0.0/docs/assets/images/image10.emf.license diff --git a/specifications/3.0.0/docs/assets/images/image10.emf.odg b/specifications/3.0.0/docs/assets/images/image10.emf.odg new file mode 100644 index 00000000..532d8f96 Binary files /dev/null and b/specifications/3.0.0/docs/assets/images/image10.emf.odg differ diff --git a/docs/assets/images/image13.emf.odg.license b/specifications/3.0.0/docs/assets/images/image10.emf.odg.license similarity index 100% rename from docs/assets/images/image13.emf.odg.license rename to specifications/3.0.0/docs/assets/images/image10.emf.odg.license diff --git a/specifications/3.0.0/docs/assets/images/image10.emf.odg.svg b/specifications/3.0.0/docs/assets/images/image10.emf.odg.svg new file mode 100644 index 00000000..169c29ce --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/image10.emf.odg.svg @@ -0,0 +1,377 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Validate + + + + + + + + + + + + + AGR + + + + + + + + + + + + + + + + DSO + + + + + + + + + + + + + + + + + + + + + + + + + + + + + AGR + + + + + + + + + + + + + + + [optional] D + - + prognosis + + + + + + + + + + + + Grid safety analysis + + NOK + + + + + + + + + + + + FlexRequest + + + + + + + + + + + + FlexOffer + + + + + + + + + + + + FlexOrder + + + + + + + + + + + + [optional] (updated) D + - + prognosis + + + + + + + + + + + + Grid safety analysis + + OK + + + + + + + + + + + + Evaluate offers + + + + + + + + + + + + [optional] D + - + prognosis + + + + + + + + + + + + FlexRequest + + + + + + + + + + + + determine offers + + + + + + + + + + + + determine offers + + + + + + + + + + + + non + - + aggregator + forecast + + + + + + + + + \ No newline at end of file diff --git a/docs/assets/images/image13.svg.license b/specifications/3.0.0/docs/assets/images/image10.emf.odg.svg.license similarity index 100% rename from docs/assets/images/image13.svg.license rename to specifications/3.0.0/docs/assets/images/image10.emf.odg.svg.license diff --git a/specifications/3.0.0/docs/assets/images/image11.emf b/specifications/3.0.0/docs/assets/images/image11.emf new file mode 100644 index 00000000..0d06846d Binary files /dev/null and b/specifications/3.0.0/docs/assets/images/image11.emf differ diff --git a/docs/assets/images/image14.emf.license b/specifications/3.0.0/docs/assets/images/image11.emf.license similarity index 100% rename from docs/assets/images/image14.emf.license rename to specifications/3.0.0/docs/assets/images/image11.emf.license diff --git a/specifications/3.0.0/docs/assets/images/image11.emf.odg b/specifications/3.0.0/docs/assets/images/image11.emf.odg new file mode 100644 index 00000000..7106e28e Binary files /dev/null and b/specifications/3.0.0/docs/assets/images/image11.emf.odg differ diff --git a/docs/assets/images/image14.emf.odg.license b/specifications/3.0.0/docs/assets/images/image11.emf.odg.license similarity index 100% rename from docs/assets/images/image14.emf.odg.license rename to specifications/3.0.0/docs/assets/images/image11.emf.odg.license diff --git a/specifications/3.0.0/docs/assets/images/image11.emf.odg.svg b/specifications/3.0.0/docs/assets/images/image11.emf.odg.svg new file mode 100644 index 00000000..34d8b394 --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/image11.emf.odg.svg @@ -0,0 +1,283 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Validate + + + + + + + + + + + + + AGR + + + + + + + + + + + + + + + + DSO + + + + + + + + + + + + + + + + + + + + + + + + + + + + FlexOffer + + + + + + + + + + + + Evaluate offers + + + + + + + + + + + + FlexRequest + + + + + + + + + + + + determine offers + + + + + + + + + + + + FlexOffer + + + + + + + + + + + + FlexOffer + + + + + + + + + + + + reconsider offer + + + + + + + + + + + + FlexOfferRevocation + + + + + + + + + + + + Evaluate offers + + + + + + + + + \ No newline at end of file diff --git a/docs/assets/images/image14.emf.odg.svg.license b/specifications/3.0.0/docs/assets/images/image11.emf.odg.svg.license similarity index 100% rename from docs/assets/images/image14.emf.odg.svg.license rename to specifications/3.0.0/docs/assets/images/image11.emf.odg.svg.license diff --git a/specifications/3.0.0/docs/assets/images/image12.emf b/specifications/3.0.0/docs/assets/images/image12.emf new file mode 100644 index 00000000..5b4ad3df Binary files /dev/null and b/specifications/3.0.0/docs/assets/images/image12.emf differ diff --git a/docs/assets/images/image15.emf.license b/specifications/3.0.0/docs/assets/images/image12.emf.license similarity index 100% rename from docs/assets/images/image15.emf.license rename to specifications/3.0.0/docs/assets/images/image12.emf.license diff --git a/specifications/3.0.0/docs/assets/images/image12.emf.odg b/specifications/3.0.0/docs/assets/images/image12.emf.odg new file mode 100644 index 00000000..4fa383e0 Binary files /dev/null and b/specifications/3.0.0/docs/assets/images/image12.emf.odg differ diff --git a/docs/assets/images/image15.emf.odg.license b/specifications/3.0.0/docs/assets/images/image12.emf.odg.license similarity index 100% rename from docs/assets/images/image15.emf.odg.license rename to specifications/3.0.0/docs/assets/images/image12.emf.odg.license diff --git a/specifications/3.0.0/docs/assets/images/image12.emf.odg.svg b/specifications/3.0.0/docs/assets/images/image12.emf.odg.svg new file mode 100644 index 00000000..be0faf4e --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/image12.emf.odg.svg @@ -0,0 +1,401 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Validate + + + + + + + + + + + Plan + + + + + + + + + + + Validate + + + + + + + + + + + + + AGR + + + + + + + + + + + + + + + + DSO + + + + + + + + + + + + + + + + + + + + + + + + + + + + FlexRequest + + + + + + + + + + + + FlexOffer + + + + + + + + + + + + (updated) D + - + prognosis + + + + + + + + + + + + determine offers + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + FlexOrder + + + + + + + + + + + + Evaluate offers + + + + + + + + + + + + re + - + optimize portfolio + + + + + + + + + + + + (updated) D + - + prognosis + + + + + + + + + + + + Grid safety analysis + + NOK + + + + + + + + + + + + FlexRequest + + + + + + + + + + + + FlexOffer + + + + + + + + + + + + determine offers + + + + + + + + + \ No newline at end of file diff --git a/docs/assets/images/image15.emf.odg.svg.license b/specifications/3.0.0/docs/assets/images/image12.emf.odg.svg.license similarity index 100% rename from docs/assets/images/image15.emf.odg.svg.license rename to specifications/3.0.0/docs/assets/images/image12.emf.odg.svg.license diff --git a/docs/assets/images/image13.emf b/specifications/3.0.0/docs/assets/images/image13.emf similarity index 100% rename from docs/assets/images/image13.emf rename to specifications/3.0.0/docs/assets/images/image13.emf diff --git a/docs/assets/images/image18.emf.license b/specifications/3.0.0/docs/assets/images/image13.emf.license similarity index 100% rename from docs/assets/images/image18.emf.license rename to specifications/3.0.0/docs/assets/images/image13.emf.license diff --git a/docs/assets/images/image13.emf.odg b/specifications/3.0.0/docs/assets/images/image13.emf.odg similarity index 100% rename from docs/assets/images/image13.emf.odg rename to specifications/3.0.0/docs/assets/images/image13.emf.odg diff --git a/docs/assets/images/image18.emf.odg.license b/specifications/3.0.0/docs/assets/images/image13.emf.odg.license similarity index 100% rename from docs/assets/images/image18.emf.odg.license rename to specifications/3.0.0/docs/assets/images/image13.emf.odg.license diff --git a/docs/assets/images/image13.svg b/specifications/3.0.0/docs/assets/images/image13.svg similarity index 100% rename from docs/assets/images/image13.svg rename to specifications/3.0.0/docs/assets/images/image13.svg diff --git a/docs/assets/images/image18.emf.odg.svg.license b/specifications/3.0.0/docs/assets/images/image13.svg.license similarity index 100% rename from docs/assets/images/image18.emf.odg.svg.license rename to specifications/3.0.0/docs/assets/images/image13.svg.license diff --git a/docs/assets/images/image14.emf b/specifications/3.0.0/docs/assets/images/image14.emf similarity index 100% rename from docs/assets/images/image14.emf rename to specifications/3.0.0/docs/assets/images/image14.emf diff --git a/docs/assets/images/image19.png.license b/specifications/3.0.0/docs/assets/images/image14.emf.license similarity index 100% rename from docs/assets/images/image19.png.license rename to specifications/3.0.0/docs/assets/images/image14.emf.license diff --git a/docs/assets/images/image14.emf.odg b/specifications/3.0.0/docs/assets/images/image14.emf.odg similarity index 100% rename from docs/assets/images/image14.emf.odg rename to specifications/3.0.0/docs/assets/images/image14.emf.odg diff --git a/docs/assets/images/image2.png.license b/specifications/3.0.0/docs/assets/images/image14.emf.odg.license similarity index 100% rename from docs/assets/images/image2.png.license rename to specifications/3.0.0/docs/assets/images/image14.emf.odg.license diff --git a/docs/assets/images/image14.emf.odg.svg b/specifications/3.0.0/docs/assets/images/image14.emf.odg.svg similarity index 100% rename from docs/assets/images/image14.emf.odg.svg rename to specifications/3.0.0/docs/assets/images/image14.emf.odg.svg diff --git a/docs/assets/images/image20.png.license b/specifications/3.0.0/docs/assets/images/image14.emf.odg.svg.license similarity index 100% rename from docs/assets/images/image20.png.license rename to specifications/3.0.0/docs/assets/images/image14.emf.odg.svg.license diff --git a/docs/assets/images/image15.emf b/specifications/3.0.0/docs/assets/images/image15.emf similarity index 100% rename from docs/assets/images/image15.emf rename to specifications/3.0.0/docs/assets/images/image15.emf diff --git a/docs/assets/images/image21.png.license b/specifications/3.0.0/docs/assets/images/image15.emf.license similarity index 100% rename from docs/assets/images/image21.png.license rename to specifications/3.0.0/docs/assets/images/image15.emf.license diff --git a/docs/assets/images/image15.emf.odg b/specifications/3.0.0/docs/assets/images/image15.emf.odg similarity index 100% rename from docs/assets/images/image15.emf.odg rename to specifications/3.0.0/docs/assets/images/image15.emf.odg diff --git a/docs/assets/images/image22.png.license b/specifications/3.0.0/docs/assets/images/image15.emf.odg.license similarity index 100% rename from docs/assets/images/image22.png.license rename to specifications/3.0.0/docs/assets/images/image15.emf.odg.license diff --git a/docs/assets/images/image15.emf.odg.svg b/specifications/3.0.0/docs/assets/images/image15.emf.odg.svg similarity index 100% rename from docs/assets/images/image15.emf.odg.svg rename to specifications/3.0.0/docs/assets/images/image15.emf.odg.svg diff --git a/docs/assets/images/image23.emf.license b/specifications/3.0.0/docs/assets/images/image15.emf.odg.svg.license similarity index 100% rename from docs/assets/images/image23.emf.license rename to specifications/3.0.0/docs/assets/images/image15.emf.odg.svg.license diff --git a/specifications/3.0.0/docs/assets/images/image16.emf b/specifications/3.0.0/docs/assets/images/image16.emf new file mode 100644 index 00000000..1d60e60a Binary files /dev/null and b/specifications/3.0.0/docs/assets/images/image16.emf differ diff --git a/docs/assets/images/image23.emf.odg.license b/specifications/3.0.0/docs/assets/images/image16.emf.license similarity index 100% rename from docs/assets/images/image23.emf.odg.license rename to specifications/3.0.0/docs/assets/images/image16.emf.license diff --git a/specifications/3.0.0/docs/assets/images/image16.emf.odg b/specifications/3.0.0/docs/assets/images/image16.emf.odg new file mode 100644 index 00000000..b45fd5de Binary files /dev/null and b/specifications/3.0.0/docs/assets/images/image16.emf.odg differ diff --git a/docs/assets/images/image23.emf.odg.svg.license b/specifications/3.0.0/docs/assets/images/image16.emf.odg.license similarity index 100% rename from docs/assets/images/image23.emf.odg.svg.license rename to specifications/3.0.0/docs/assets/images/image16.emf.odg.license diff --git a/specifications/3.0.0/docs/assets/images/image16.emf.odg.svg b/specifications/3.0.0/docs/assets/images/image16.emf.odg.svg new file mode 100644 index 00000000..4923d36f --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/image16.emf.odg.svg @@ -0,0 +1,275 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Operate + + + + + + + + + + + + + AGR + + + + + + + + + + + + + + + + DSO + + + + + + + + + + + + + + + + + + + + + + + + + + + + Evaluate offers + + + + + + + + + + + + FlexOrder + + + + + + + + + + + + reconsider offer + + + + + + + + + + + + FlexOfferRevocation + + + + + + + + + + + + Grid safety analysis + + NOK + + + + + + + + + + + + (updated) D + - + prognosis + + + + + + + + + + + + control portfolio + + + + + + + + + \ No newline at end of file diff --git a/docs/assets/images/image24.emf.license b/specifications/3.0.0/docs/assets/images/image16.emf.odg.svg.license similarity index 100% rename from docs/assets/images/image24.emf.license rename to specifications/3.0.0/docs/assets/images/image16.emf.odg.svg.license diff --git a/specifications/3.0.0/docs/assets/images/image17.emf b/specifications/3.0.0/docs/assets/images/image17.emf new file mode 100644 index 00000000..9e61a55c Binary files /dev/null and b/specifications/3.0.0/docs/assets/images/image17.emf differ diff --git a/docs/assets/images/image24.emf.odg.license b/specifications/3.0.0/docs/assets/images/image17.emf.license similarity index 100% rename from docs/assets/images/image24.emf.odg.license rename to specifications/3.0.0/docs/assets/images/image17.emf.license diff --git a/specifications/3.0.0/docs/assets/images/image17.emf.odg b/specifications/3.0.0/docs/assets/images/image17.emf.odg new file mode 100644 index 00000000..94fd016a Binary files /dev/null and b/specifications/3.0.0/docs/assets/images/image17.emf.odg differ diff --git a/docs/assets/images/image24.emf.odg.svg.license b/specifications/3.0.0/docs/assets/images/image17.emf.odg.license similarity index 100% rename from docs/assets/images/image24.emf.odg.svg.license rename to specifications/3.0.0/docs/assets/images/image17.emf.odg.license diff --git a/specifications/3.0.0/docs/assets/images/image17.emf.odg.svg b/specifications/3.0.0/docs/assets/images/image17.emf.odg.svg new file mode 100644 index 00000000..98f7a115 --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/image17.emf.odg.svg @@ -0,0 +1,316 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Settle + + + + + + + + + + + + + AGR + + + + + + + + + + + + + + + + DSO + + + + + + + + + + + + + + + + + + + + + + + + + + + + Response: accepted + OR + disputed + + + + + + + + + + + + FlexSettlement + + + + + + + + + + + + calculate flex fee + (and penalty) + + + + + + + + + + + + calculate procured + flexibility + + + + + + + + + + + + calculate sold + flexibility + + + + + + + + + + + + collect meter data + + + + + + + + + + + + validate if baselines + are met + + + + + + + + + + + + validate if baselines + are met + + + + + + + + + + + + validate with own + calculations + + + + + + + + + + + + calculate flex fee + (and penalty) + + + + + + + + + \ No newline at end of file diff --git a/docs/assets/images/image24.svg.license b/specifications/3.0.0/docs/assets/images/image17.emf.odg.svg.license similarity index 100% rename from docs/assets/images/image24.svg.license rename to specifications/3.0.0/docs/assets/images/image17.emf.odg.svg.license diff --git a/docs/assets/images/image18.emf b/specifications/3.0.0/docs/assets/images/image18.emf similarity index 100% rename from docs/assets/images/image18.emf rename to specifications/3.0.0/docs/assets/images/image18.emf diff --git a/docs/assets/images/image25.png.license b/specifications/3.0.0/docs/assets/images/image18.emf.license similarity index 100% rename from docs/assets/images/image25.png.license rename to specifications/3.0.0/docs/assets/images/image18.emf.license diff --git a/docs/assets/images/image18.emf.odg b/specifications/3.0.0/docs/assets/images/image18.emf.odg similarity index 100% rename from docs/assets/images/image18.emf.odg rename to specifications/3.0.0/docs/assets/images/image18.emf.odg diff --git a/docs/assets/images/image3.emf.license b/specifications/3.0.0/docs/assets/images/image18.emf.odg.license similarity index 100% rename from docs/assets/images/image3.emf.license rename to specifications/3.0.0/docs/assets/images/image18.emf.odg.license diff --git a/docs/assets/images/image18.emf.odg.svg b/specifications/3.0.0/docs/assets/images/image18.emf.odg.svg similarity index 100% rename from docs/assets/images/image18.emf.odg.svg rename to specifications/3.0.0/docs/assets/images/image18.emf.odg.svg diff --git a/docs/assets/images/image3.emf.odg.license b/specifications/3.0.0/docs/assets/images/image18.emf.odg.svg.license similarity index 100% rename from docs/assets/images/image3.emf.odg.license rename to specifications/3.0.0/docs/assets/images/image18.emf.odg.svg.license diff --git a/docs/assets/images/image19.png b/specifications/3.0.0/docs/assets/images/image19.png similarity index 100% rename from docs/assets/images/image19.png rename to specifications/3.0.0/docs/assets/images/image19.png diff --git a/docs/assets/images/image3.emf.odg.svg.license b/specifications/3.0.0/docs/assets/images/image19.png.license similarity index 100% rename from docs/assets/images/image3.emf.odg.svg.license rename to specifications/3.0.0/docs/assets/images/image19.png.license diff --git a/docs/assets/images/image2.png b/specifications/3.0.0/docs/assets/images/image2.png similarity index 100% rename from docs/assets/images/image2.png rename to specifications/3.0.0/docs/assets/images/image2.png diff --git a/docs/assets/images/image4.emf.license b/specifications/3.0.0/docs/assets/images/image2.png.license similarity index 100% rename from docs/assets/images/image4.emf.license rename to specifications/3.0.0/docs/assets/images/image2.png.license diff --git a/docs/assets/images/image20.png b/specifications/3.0.0/docs/assets/images/image20.png similarity index 100% rename from docs/assets/images/image20.png rename to specifications/3.0.0/docs/assets/images/image20.png diff --git a/docs/assets/images/image4.emf.odg.license b/specifications/3.0.0/docs/assets/images/image20.png.license similarity index 100% rename from docs/assets/images/image4.emf.odg.license rename to specifications/3.0.0/docs/assets/images/image20.png.license diff --git a/docs/assets/images/image21.png b/specifications/3.0.0/docs/assets/images/image21.png similarity index 100% rename from docs/assets/images/image21.png rename to specifications/3.0.0/docs/assets/images/image21.png diff --git a/docs/assets/images/image4.emf.odg.svg.license b/specifications/3.0.0/docs/assets/images/image21.png.license similarity index 100% rename from docs/assets/images/image4.emf.odg.svg.license rename to specifications/3.0.0/docs/assets/images/image21.png.license diff --git a/docs/assets/images/image22.png b/specifications/3.0.0/docs/assets/images/image22.png similarity index 100% rename from docs/assets/images/image22.png rename to specifications/3.0.0/docs/assets/images/image22.png diff --git a/docs/assets/images/image5.png.license b/specifications/3.0.0/docs/assets/images/image22.png.license similarity index 100% rename from docs/assets/images/image5.png.license rename to specifications/3.0.0/docs/assets/images/image22.png.license diff --git a/docs/assets/images/image23.emf b/specifications/3.0.0/docs/assets/images/image23.emf similarity index 100% rename from docs/assets/images/image23.emf rename to specifications/3.0.0/docs/assets/images/image23.emf diff --git a/docs/assets/images/image6.png.license b/specifications/3.0.0/docs/assets/images/image23.emf.license similarity index 100% rename from docs/assets/images/image6.png.license rename to specifications/3.0.0/docs/assets/images/image23.emf.license diff --git a/docs/assets/images/image23.emf.odg b/specifications/3.0.0/docs/assets/images/image23.emf.odg similarity index 100% rename from docs/assets/images/image23.emf.odg rename to specifications/3.0.0/docs/assets/images/image23.emf.odg diff --git a/docs/assets/images/image8.emf.license b/specifications/3.0.0/docs/assets/images/image23.emf.odg.license similarity index 100% rename from docs/assets/images/image8.emf.license rename to specifications/3.0.0/docs/assets/images/image23.emf.odg.license diff --git a/docs/assets/images/image23.emf.odg.svg b/specifications/3.0.0/docs/assets/images/image23.emf.odg.svg similarity index 100% rename from docs/assets/images/image23.emf.odg.svg rename to specifications/3.0.0/docs/assets/images/image23.emf.odg.svg diff --git a/docs/assets/images/image8.emf.odg.license b/specifications/3.0.0/docs/assets/images/image23.emf.odg.svg.license similarity index 100% rename from docs/assets/images/image8.emf.odg.license rename to specifications/3.0.0/docs/assets/images/image23.emf.odg.svg.license diff --git a/docs/assets/images/image24.emf b/specifications/3.0.0/docs/assets/images/image24.emf similarity index 100% rename from docs/assets/images/image24.emf rename to specifications/3.0.0/docs/assets/images/image24.emf diff --git a/docs/assets/images/image8.emf.odg.svg.license b/specifications/3.0.0/docs/assets/images/image24.emf.license similarity index 100% rename from docs/assets/images/image8.emf.odg.svg.license rename to specifications/3.0.0/docs/assets/images/image24.emf.license diff --git a/docs/assets/images/image24.emf.odg b/specifications/3.0.0/docs/assets/images/image24.emf.odg similarity index 100% rename from docs/assets/images/image24.emf.odg rename to specifications/3.0.0/docs/assets/images/image24.emf.odg diff --git a/docs/assets/images/shapeshifter-horizontal-color.svg.license b/specifications/3.0.0/docs/assets/images/image24.emf.odg.license similarity index 100% rename from docs/assets/images/shapeshifter-horizontal-color.svg.license rename to specifications/3.0.0/docs/assets/images/image24.emf.odg.license diff --git a/docs/assets/images/image24.emf.odg.svg b/specifications/3.0.0/docs/assets/images/image24.emf.odg.svg similarity index 100% rename from docs/assets/images/image24.emf.odg.svg rename to specifications/3.0.0/docs/assets/images/image24.emf.odg.svg diff --git a/docs/assets/images/shapeshifter-icon-color.svg.license b/specifications/3.0.0/docs/assets/images/image24.emf.odg.svg.license similarity index 100% rename from docs/assets/images/shapeshifter-icon-color.svg.license rename to specifications/3.0.0/docs/assets/images/image24.emf.odg.svg.license diff --git a/docs/assets/images/image24.svg b/specifications/3.0.0/docs/assets/images/image24.svg similarity index 100% rename from docs/assets/images/image24.svg rename to specifications/3.0.0/docs/assets/images/image24.svg diff --git a/docs/assets/images/shapeshifter-icon-white.svg.license b/specifications/3.0.0/docs/assets/images/image24.svg.license similarity index 100% rename from docs/assets/images/shapeshifter-icon-white.svg.license rename to specifications/3.0.0/docs/assets/images/image24.svg.license diff --git a/docs/assets/images/image25.png b/specifications/3.0.0/docs/assets/images/image25.png similarity index 100% rename from docs/assets/images/image25.png rename to specifications/3.0.0/docs/assets/images/image25.png diff --git a/specifications/3.0.0/docs/assets/images/image25.png.license b/specifications/3.0.0/docs/assets/images/image25.png.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/image25.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/assets/images/image3.emf b/specifications/3.0.0/docs/assets/images/image3.emf similarity index 100% rename from docs/assets/images/image3.emf rename to specifications/3.0.0/docs/assets/images/image3.emf diff --git a/specifications/3.0.0/docs/assets/images/image3.emf.license b/specifications/3.0.0/docs/assets/images/image3.emf.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/image3.emf.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/assets/images/image3.emf.odg b/specifications/3.0.0/docs/assets/images/image3.emf.odg similarity index 100% rename from docs/assets/images/image3.emf.odg rename to specifications/3.0.0/docs/assets/images/image3.emf.odg diff --git a/specifications/3.0.0/docs/assets/images/image3.emf.odg.license b/specifications/3.0.0/docs/assets/images/image3.emf.odg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/image3.emf.odg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/assets/images/image3.emf.odg.svg b/specifications/3.0.0/docs/assets/images/image3.emf.odg.svg similarity index 100% rename from docs/assets/images/image3.emf.odg.svg rename to specifications/3.0.0/docs/assets/images/image3.emf.odg.svg diff --git a/specifications/3.0.0/docs/assets/images/image3.emf.odg.svg.license b/specifications/3.0.0/docs/assets/images/image3.emf.odg.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/image3.emf.odg.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/assets/images/image4.emf b/specifications/3.0.0/docs/assets/images/image4.emf similarity index 100% rename from docs/assets/images/image4.emf rename to specifications/3.0.0/docs/assets/images/image4.emf diff --git a/specifications/3.0.0/docs/assets/images/image4.emf.license b/specifications/3.0.0/docs/assets/images/image4.emf.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/image4.emf.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/assets/images/image4.emf.odg b/specifications/3.0.0/docs/assets/images/image4.emf.odg similarity index 100% rename from docs/assets/images/image4.emf.odg rename to specifications/3.0.0/docs/assets/images/image4.emf.odg diff --git a/specifications/3.0.0/docs/assets/images/image4.emf.odg.license b/specifications/3.0.0/docs/assets/images/image4.emf.odg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/image4.emf.odg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/assets/images/image4.emf.odg.svg b/specifications/3.0.0/docs/assets/images/image4.emf.odg.svg similarity index 100% rename from docs/assets/images/image4.emf.odg.svg rename to specifications/3.0.0/docs/assets/images/image4.emf.odg.svg diff --git a/specifications/3.0.0/docs/assets/images/image4.emf.odg.svg.license b/specifications/3.0.0/docs/assets/images/image4.emf.odg.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/image4.emf.odg.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/assets/images/image5.png b/specifications/3.0.0/docs/assets/images/image5.png similarity index 100% rename from docs/assets/images/image5.png rename to specifications/3.0.0/docs/assets/images/image5.png diff --git a/specifications/3.0.0/docs/assets/images/image5.png.license b/specifications/3.0.0/docs/assets/images/image5.png.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/image5.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/assets/images/image6.png b/specifications/3.0.0/docs/assets/images/image6.png similarity index 100% rename from docs/assets/images/image6.png rename to specifications/3.0.0/docs/assets/images/image6.png diff --git a/specifications/3.0.0/docs/assets/images/image6.png.license b/specifications/3.0.0/docs/assets/images/image6.png.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/image6.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.0.0/docs/assets/images/image7.emf b/specifications/3.0.0/docs/assets/images/image7.emf new file mode 100644 index 00000000..50dff2b2 Binary files /dev/null and b/specifications/3.0.0/docs/assets/images/image7.emf differ diff --git a/specifications/3.0.0/docs/assets/images/image7.emf.license b/specifications/3.0.0/docs/assets/images/image7.emf.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/image7.emf.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.0.0/docs/assets/images/image7.emf.odg b/specifications/3.0.0/docs/assets/images/image7.emf.odg new file mode 100644 index 00000000..722bbfb0 Binary files /dev/null and b/specifications/3.0.0/docs/assets/images/image7.emf.odg differ diff --git a/specifications/3.0.0/docs/assets/images/image7.emf.odg.license b/specifications/3.0.0/docs/assets/images/image7.emf.odg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/image7.emf.odg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.0.0/docs/assets/images/image7.emf.odg.svg b/specifications/3.0.0/docs/assets/images/image7.emf.odg.svg new file mode 100644 index 00000000..e6c42905 --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/image7.emf.odg.svg @@ -0,0 +1,284 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Contract + + + + + + + + + + + + + + publish connections related to + contracted Prosumers + + + + + + + + + + + + publish congestion points + incl. connections + + + + + + + + + + + + CRO + + + + + + + + + + + + + + + + DSO + + + + + + + + + + + + + + + + + + + + + + + + + + + + + AGR + + + + + + + + + + + + + + + + [optional] negotiate + FlexOption + + + + + + + + + + + + Pre + - + Q asset(s) + + + + + + + + + + + + contract Prosumers + + + + + + + + + + + + + Pre + - + qualification AGR + + + + + + + + + \ No newline at end of file diff --git a/specifications/3.0.0/docs/assets/images/image7.emf.odg.svg.license b/specifications/3.0.0/docs/assets/images/image7.emf.odg.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/image7.emf.odg.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/assets/images/image8.emf b/specifications/3.0.0/docs/assets/images/image8.emf similarity index 100% rename from docs/assets/images/image8.emf rename to specifications/3.0.0/docs/assets/images/image8.emf diff --git a/specifications/3.0.0/docs/assets/images/image8.emf.license b/specifications/3.0.0/docs/assets/images/image8.emf.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/image8.emf.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/assets/images/image8.emf.odg b/specifications/3.0.0/docs/assets/images/image8.emf.odg similarity index 100% rename from docs/assets/images/image8.emf.odg rename to specifications/3.0.0/docs/assets/images/image8.emf.odg diff --git a/specifications/3.0.0/docs/assets/images/image8.emf.odg.license b/specifications/3.0.0/docs/assets/images/image8.emf.odg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/image8.emf.odg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/assets/images/image8.emf.odg.svg b/specifications/3.0.0/docs/assets/images/image8.emf.odg.svg similarity index 100% rename from docs/assets/images/image8.emf.odg.svg rename to specifications/3.0.0/docs/assets/images/image8.emf.odg.svg diff --git a/specifications/3.0.0/docs/assets/images/image8.emf.odg.svg.license b/specifications/3.0.0/docs/assets/images/image8.emf.odg.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/image8.emf.odg.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.0.0/docs/assets/images/image9.emf b/specifications/3.0.0/docs/assets/images/image9.emf new file mode 100644 index 00000000..80ac0bd9 Binary files /dev/null and b/specifications/3.0.0/docs/assets/images/image9.emf differ diff --git a/specifications/3.0.0/docs/assets/images/image9.emf.license b/specifications/3.0.0/docs/assets/images/image9.emf.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/image9.emf.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.0.0/docs/assets/images/image9.emf.odg b/specifications/3.0.0/docs/assets/images/image9.emf.odg new file mode 100644 index 00000000..564fc307 Binary files /dev/null and b/specifications/3.0.0/docs/assets/images/image9.emf.odg differ diff --git a/specifications/3.0.0/docs/assets/images/image9.emf.odg.license b/specifications/3.0.0/docs/assets/images/image9.emf.odg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/image9.emf.odg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.0.0/docs/assets/images/image9.emf.odg.svg b/specifications/3.0.0/docs/assets/images/image9.emf.odg.svg new file mode 100644 index 00000000..76d520f4 --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/image9.emf.odg.svg @@ -0,0 +1,272 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Plan + + + + + + + + + + + + + + Retrieve list congestion points + incl. associated connections + + + + + + + + + + + + Retrieve ‘active’ Aggregators + for each congestion point + + + + + + + + + + + + CRO + + + + + + + + + + + + + + + + optimize portfolio + + + + + + + + + + + + DSO + + + + + + + + + + + + + + + + + + + + + + + + + + + + + AGR + + + + + + + + + + + + + + + [ + optional + ] FlexReservationUpdate + + + + + + + + + + + + optimize portfolio + + + + + + + + + \ No newline at end of file diff --git a/specifications/3.0.0/docs/assets/images/image9.emf.odg.svg.license b/specifications/3.0.0/docs/assets/images/image9.emf.odg.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/image9.emf.odg.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/assets/images/shapeshifter-horizontal-color.svg b/specifications/3.0.0/docs/assets/images/shapeshifter-horizontal-color.svg similarity index 100% rename from docs/assets/images/shapeshifter-horizontal-color.svg rename to specifications/3.0.0/docs/assets/images/shapeshifter-horizontal-color.svg diff --git a/specifications/3.0.0/docs/assets/images/shapeshifter-horizontal-color.svg.license b/specifications/3.0.0/docs/assets/images/shapeshifter-horizontal-color.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/shapeshifter-horizontal-color.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/assets/images/shapeshifter-icon-color.svg b/specifications/3.0.0/docs/assets/images/shapeshifter-icon-color.svg similarity index 100% rename from docs/assets/images/shapeshifter-icon-color.svg rename to specifications/3.0.0/docs/assets/images/shapeshifter-icon-color.svg diff --git a/specifications/3.0.0/docs/assets/images/shapeshifter-icon-color.svg.license b/specifications/3.0.0/docs/assets/images/shapeshifter-icon-color.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/shapeshifter-icon-color.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/assets/images/shapeshifter-icon-white.svg b/specifications/3.0.0/docs/assets/images/shapeshifter-icon-white.svg similarity index 100% rename from docs/assets/images/shapeshifter-icon-white.svg rename to specifications/3.0.0/docs/assets/images/shapeshifter-icon-white.svg diff --git a/specifications/3.0.0/docs/assets/images/shapeshifter-icon-white.svg.license b/specifications/3.0.0/docs/assets/images/shapeshifter-icon-white.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/shapeshifter-icon-white.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.0.0/docs/assets/images/use-case-3-1-exchange-of-congestions-points.odg b/specifications/3.0.0/docs/assets/images/use-case-3-1-exchange-of-congestions-points.odg new file mode 100644 index 00000000..f0b7c00a Binary files /dev/null and b/specifications/3.0.0/docs/assets/images/use-case-3-1-exchange-of-congestions-points.odg differ diff --git a/specifications/3.0.0/docs/assets/images/use-case-3-1-exchange-of-congestions-points.odg.license b/specifications/3.0.0/docs/assets/images/use-case-3-1-exchange-of-congestions-points.odg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/use-case-3-1-exchange-of-congestions-points.odg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.0.0/docs/assets/images/use-case-3-1-exchange-of-congestions-points.odg.svg b/specifications/3.0.0/docs/assets/images/use-case-3-1-exchange-of-congestions-points.odg.svg new file mode 100644 index 00000000..f6df0a13 --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/use-case-3-1-exchange-of-congestions-points.odg.svg @@ -0,0 +1,457 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + alt + + + + + + + [if CRO is operating in open mode] + + + + + + + + + + + + + + + DSOPortfolioUpdateResponse Result=Accepted + + + + + + + + + + + + + + HTTP OK + + + + + + + + DSOPortfolioUpdateResonse Result=Rejected + + + + + + + + + + + + + + + + + + + + HTTP OK + + + + + + + + + + + + + + + + CRO + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + alt + + + + + + + [if DSO is an authorized participant] + + + + + + + + + + + + + + + DSOPortfolioUpdateResponse Result=Accepted + + + + + + + + + + + + + + HTTP OK + + + + + + + + + + + + + + + + DSOPortfolioUpdate + + + + + + + + + + + + + + HTTP OK + + + + + + + + + + + + + + + + DSO + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/specifications/3.0.0/docs/assets/images/use-case-3-1-exchange-of-congestions-points.odg.svg.license b/specifications/3.0.0/docs/assets/images/use-case-3-1-exchange-of-congestions-points.odg.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/use-case-3-1-exchange-of-congestions-points.odg.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.0.0/docs/assets/images/use-case-3-1-exchange-of-congestions-points.svg b/specifications/3.0.0/docs/assets/images/use-case-3-1-exchange-of-congestions-points.svg new file mode 100644 index 00000000..8fa366d3 --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/use-case-3-1-exchange-of-congestions-points.svg @@ -0,0 +1,2944 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + alt + + + + + + + + + + + + + + + + [if CRO is operating in open mode] + + + + + + + + + + + + + + + + DSOPortfolioUpdateResponse Result=Accepted + + + + + + + + + + + + + + + + HTTP OK + + + + + + + + + + + + + + + DSOPortfolioUpdateResponse Result=Rejected + + + + + + + + + + + + + + + + + HTTP OK + + + + + + + + + + + + + + + + + CRO + + + + + + + + + + + + + + + + + + + + + + + + alt + + + + + + + + + + + + + + + + [if DSO is an authorized participant] + + + + + + + + + + + + + + + + DSOPortfolioUpdateResponse Result=Accepted + + + + + + + + + + + + + + + + HTTP OK + + + + + + + + + + + + + + + + DSOPortfolioUpdate + + + + + + + + + + + + + + + + HTTP OK + + + + + + + + + + + + + + + + + DSO + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/specifications/3.0.0/docs/assets/images/use-case-3-1-exchange-of-congestions-points.svg.license b/specifications/3.0.0/docs/assets/images/use-case-3-1-exchange-of-congestions-points.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/use-case-3-1-exchange-of-congestions-points.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.0.0/docs/assets/images/use-case-3-10-exchange-of-flexoffer.svg b/specifications/3.0.0/docs/assets/images/use-case-3-10-exchange-of-flexoffer.svg new file mode 100644 index 00000000..4aa55a1b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/use-case-3-10-exchange-of-flexoffer.svg @@ -0,0 +1,2739 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + AGR + + + + + + + + + + + + + + + + + + + + + DSO + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + loop + + + + + + + + + + + + + + + + [for each available FlexOffer to be accepted] + + + + + + + + + + + + + + + + + alt + + + + + + + + + + + + + + + + [if FlexOrder is valid] + + + + + + + + + + + + + + + + FlexOrder + + + + + + + + + + + + + + + HTTP OK + + + + + + + + + + + + + + + + + FlexOrderResponse Result=Accepted + + + + + + + + + + + + + + + + HTTP OK + + + + + + + + + + + + + + + FlexOrderResponse Result=Rejected + + + + + + + + + + + + + + + + + HTTP OK + + + + + + + + diff --git a/specifications/3.0.0/docs/assets/images/use-case-3-10-exchange-of-flexoffer.svg.license b/specifications/3.0.0/docs/assets/images/use-case-3-10-exchange-of-flexoffer.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/use-case-3-10-exchange-of-flexoffer.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.0.0/docs/assets/images/use-case-3-11-transmission-of-settlement.svg b/specifications/3.0.0/docs/assets/images/use-case-3-11-transmission-of-settlement.svg new file mode 100644 index 00000000..36e814c2 --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/use-case-3-11-transmission-of-settlement.svg @@ -0,0 +1,3032 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + AGR + + + + + + + + + + + + + + + + + + + + + DSO + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + alt + + + + + + + + + + + + + + + + [if FlexSettlement is valid] + + + + + + + + + + + + + + + + FlexSettlement + + + + + + + + + + + + + + + HTTP OK + + + + + + + + + + + + + + + + + FlexSettlementResponse Result=Accepted + + + + + + + + + + + + + + + + HTTP OK + + + + + + + + + + + + + + + FlexSettlementResponse Result=Rejected + + + + + + + + + + + + + + + + + HTTP OK + + + + + + + + + + + + + + + + + loop + + + + + + + + + + + + + + + + [for each FlexOrderSettlement in FlexSettlement] + + + + + + + + + + + + + + + Disposition=Accepted + + + + + + + + + + + + + + + Disposition=Disputed + + + + + + + + + + + + + + + + + + + + alt + + + + + + + + + + + + + + + + [if settlement details are + + + + + accepted] + + + + + + + + diff --git a/specifications/3.0.0/docs/assets/images/use-case-3-11-transmission-of-settlement.svg.license b/specifications/3.0.0/docs/assets/images/use-case-3-11-transmission-of-settlement.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/use-case-3-11-transmission-of-settlement.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.0.0/docs/assets/images/use-case-3-2-exchange-of-connections-by-agr.svg b/specifications/3.0.0/docs/assets/images/use-case-3-2-exchange-of-connections-by-agr.svg new file mode 100644 index 00000000..c3596998 --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/use-case-3-2-exchange-of-connections-by-agr.svg @@ -0,0 +1,2650 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + alt + + + + + + + + + + + + + + + + [if CRO is operating in open mode] + + + + + + + + + + + + + + + + AGRPortfolioUpdateResponse + + + + + Result=Accepted + + + + + + + + + + + + + + + + HTTP + + + + + OK + + + + + + + + + + + + + + + AGRPortfolioUpdateResponse Result=Rejected + + + + + + + + + + + + + + + + + HTTP + + + + + OK + + + + + + + + + + + + + + + + + CRO + + + + + + + + + + + + + + + + + + + + + + + + alt + + + + + + + + + + + + + + + + [if AGR is an authorized participant] + + + + + + + + + + + + + + + + AGRPortfolioUpdateResponse + + + + + Result=Accepted + + + + + + + + + + + + + + + + HTTP + + + + + OK + + + + + + + + + + + + + + + + + AGR + + + + + + + + + + + + + + + + + + + AGRPortfolioUpdate + + + + + + + + + + + + + + + + HTTP + + + + + OK + + + + + + + + diff --git a/specifications/3.0.0/docs/assets/images/use-case-3-2-exchange-of-connections-by-agr.svg.license b/specifications/3.0.0/docs/assets/images/use-case-3-2-exchange-of-connections-by-agr.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/use-case-3-2-exchange-of-connections-by-agr.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.0.0/docs/assets/images/use-case-3-3-retrieval-of-congestion-points.svg b/specifications/3.0.0/docs/assets/images/use-case-3-3-retrieval-of-congestion-points.svg new file mode 100644 index 00000000..d733dabe --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/use-case-3-3-retrieval-of-congestion-points.svg @@ -0,0 +1,2714 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + alt + + + + + + + + + + + + + + + + [if CRO is operating in open mode] + + + + + + + + + + + + + + + + AGRPortfolioQueryResponse Result=Accepted + + + + + + + + + + + + + + + + HTTP OK + + + + + + + + + + + + + + + AGRPortfolioQueryResponse Result=Rejected + + + + + + + + + + + + + + + + + HTTP OK + + + + + + + + + + + + + + + + + CRO + + + + + + + + + + + + + + + + + + + + + + + + alt + + + + + + + + + + + + + + + + [if AGR is an + + + + + authorized participant] + + + + + + + + + + + + + + + + AGRPortfolioQueryResponse Result=Accepted + + + + + + + + + + + + + + + + HTTP OK + + + + + + + + + + + + + + + + AGRPortfolioQuery + + + + + + + + + + + + + + + + HTTP OK + + + + + + + + + + + + + + + + + AGR + + + + + + + + + + + diff --git a/specifications/3.0.0/docs/assets/images/use-case-3-3-retrieval-of-congestion-points.svg.license b/specifications/3.0.0/docs/assets/images/use-case-3-3-retrieval-of-congestion-points.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/use-case-3-3-retrieval-of-congestion-points.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.0.0/docs/assets/images/use-case-3-4-retrieval-of-registered-connections.svg b/specifications/3.0.0/docs/assets/images/use-case-3-4-retrieval-of-registered-connections.svg new file mode 100644 index 00000000..bbd0e657 --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/use-case-3-4-retrieval-of-registered-connections.svg @@ -0,0 +1,2678 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + DSO + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + alt + + + + + + + + + + + + + + + + [if CRO is operating in open mode] + + + + + + + + + + + + + + + + DSOPortfolioQueryResponse Result=Accepted + + + + + + + + + + + + + + + + HTTP OK + + + + + + + + + + + + + + + DSOPortfolioQueryResponse + + + + + Result=Rejected + + + + + + + + + + + + + + + + + HTTP OK + + + + + + + + + + + + + + + + + CRO + + + + + + + + + + + + + + + + + + + + + + + + alt + + + + + + + + + + + + + + + + [if DSO is an authorized participant] + + + + + + + + + + + + + + + + DSOPortfolioQueryResponse Result=Accepted + + + + + + + + + + + + + + + + HTTP OK + + + + + + + + + + + + + + + + DSOPortfolioQuery + + + + + + + + + + + + + + + + HTTP OK + + + + + + + + diff --git a/specifications/3.0.0/docs/assets/images/use-case-3-4-retrieval-of-registered-connections.svg.license b/specifications/3.0.0/docs/assets/images/use-case-3-4-retrieval-of-registered-connections.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/use-case-3-4-retrieval-of-registered-connections.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.0.0/docs/assets/images/use-case-3-5-exchange-of-flexreservationupdate.svg b/specifications/3.0.0/docs/assets/images/use-case-3-5-exchange-of-flexreservationupdate.svg new file mode 100644 index 00000000..1715e2bc --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/use-case-3-5-exchange-of-flexreservationupdate.svg @@ -0,0 +1,2533 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + AGR + + + + + + + + + + + + + + + + + + + + + DSO + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + loop + + + + + + + + + + + + + + + + [for each contracted flex reservation in a certain period] + + + + + + + + + + + + + + + + + alt + + + + + + + + + + + + + + + + [if FlexReservationUpdate is valid] + + + + + + + + + + + + + + + + FlexReservationUpdate + + + + + + + + + + + + + + + HTTP OK + + + + + + + + + + + + + + + + FlexReservationUpdateResponse Result=Rejected + + + + + + + + + + + + + + + + + HTTP OK + + + + + + + + + + + + + + + FlexReservationUpdateResponse Result=Accepted + + + + + + + + + + + + + + + + + HTTP OK + + + + + + + + diff --git a/specifications/3.0.0/docs/assets/images/use-case-3-5-exchange-of-flexreservationupdate.svg.license b/specifications/3.0.0/docs/assets/images/use-case-3-5-exchange-of-flexreservationupdate.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/use-case-3-5-exchange-of-flexreservationupdate.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.0.0/docs/assets/images/use-case-3-6-exchange-of-d-prognoses.svg b/specifications/3.0.0/docs/assets/images/use-case-3-6-exchange-of-d-prognoses.svg new file mode 100644 index 00000000..5bbfb429 --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/use-case-3-6-exchange-of-d-prognoses.svg @@ -0,0 +1,3358 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + AGR + + + + + + + + + + + + + + + + + + + + + DSO + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + loop + + + + + + + + + + + + + + + + [for each Congestion Point + + + + + with contracted Prosumers] + + + + + + + + + + + + + + + + + alt + + + + + + + + + + + + + + + + [if D + + + + + - + + + + + prognosis is valid] + + + + + + + + + + + + + + + + D + + + + + - + + + + + Prognosis + + + + + + + + + + + + + + + HTTP OK + + + + + + + + + + + + + + + + + D + + + + + - + + + + + PrognosisResponse + + + + + + + + + + + + + + + + HTTP OK + + + + + + + + + + + + + + + D + + + + + - + + + + + PrognosisResponse + + + + + + + + + + + + + + + + + HTTP OK + + + + + + + + diff --git a/specifications/3.0.0/docs/assets/images/use-case-3-6-exchange-of-d-prognoses.svg.license b/specifications/3.0.0/docs/assets/images/use-case-3-6-exchange-of-d-prognoses.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/use-case-3-6-exchange-of-d-prognoses.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.0.0/docs/assets/images/use-case-3-7-exchange-of-flexrequests.svg b/specifications/3.0.0/docs/assets/images/use-case-3-7-exchange-of-flexrequests.svg new file mode 100644 index 00000000..236d0ab2 --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/use-case-3-7-exchange-of-flexrequests.svg @@ -0,0 +1,2731 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + AGR + + + + + + + + + + + + + + + + + + + + + DSO + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + loop + + + + + + + + + + + + + + + + [for each Congestion Point with expected congestion in a certain period] + + + + + + + + + + + + + + + + + alt + + + + + + + + + + + + + + + + [if + + + + + FlexRequest is valid] + + + + + + + + + + + + + + + + FlexRequest + + + + + + + + + + + + + + + HTTP OK + + + + + + + + + + + + + + + + + FlexRequestResponse + + + + + Result=Accepted + + + + + + + + + + + + + + + + HTTP OK + + + + + + + + + + + + + + + FlexRequestResponse + + + + + Result=Rejected + + + + + + + + + + + + + + + + + HTTP OK + + + + + + + + diff --git a/specifications/3.0.0/docs/assets/images/use-case-3-7-exchange-of-flexrequests.svg.license b/specifications/3.0.0/docs/assets/images/use-case-3-7-exchange-of-flexrequests.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/use-case-3-7-exchange-of-flexrequests.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.0.0/docs/assets/images/use-case-3-8-exchange-of-flexoffers.svg b/specifications/3.0.0/docs/assets/images/use-case-3-8-exchange-of-flexoffers.svg new file mode 100644 index 00000000..5bcd8f4f --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/use-case-3-8-exchange-of-flexoffers.svg @@ -0,0 +1,3000 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + AGR + + + + + + + + + + + + + + + + + + + + + DSO + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + FlexOffer + + + + + + + + + + + + + + + + + + + + + loop + + + + + + + + + + + + + + + + [for each open flexibility request or unsolicited flexibility offer] + + + + + + + + + + + + + + + + + + loop + + + + + + + + + + + + + + + + [for each + + + + + self + + + + + - + + + + + containing flexibility offer] + + + + + + + + + + + + + + + + + + alt + + + + + + + + + + + + + + + + [if FlexOffer is valid] + + + + + + + + + + + + + + + + HTTP OK + + + + + + + + + + + + + + + FlexOfferResponse Result=Rejected + + + + + + + + + + + + + + + + + HTTP OK + + + + + + + + + + + + + + + FlexOfferResponse Result=Accepted + + + + + + + + + + + + + + + + + HTTP OK + + + + + + + + diff --git a/specifications/3.0.0/docs/assets/images/use-case-3-8-exchange-of-flexoffers.svg.license b/specifications/3.0.0/docs/assets/images/use-case-3-8-exchange-of-flexoffers.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/use-case-3-8-exchange-of-flexoffers.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.0.0/docs/assets/images/use-case-3-9-revocation-of-flexoffer.svg b/specifications/3.0.0/docs/assets/images/use-case-3-9-revocation-of-flexoffer.svg new file mode 100644 index 00000000..f2217197 --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/use-case-3-9-revocation-of-flexoffer.svg @@ -0,0 +1,2913 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + AGR + + + + + + + + + + + + + + + + + + + + + DSO + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + loop + + + + + + + + + + + + + + + [for each successfully transmitted FlexOffer to be revoked] + + + + + + + + + + + + + + + + + alt + + + + + + + + + + + + + + + + [if FlexOfferRevocation is valid] + + + + + + + + + + + + + + + + FlexOfferRevocation + + + + + + + + + + + + + + + HTTP + + + + + OK + + + + + + + + + + + + + + + + FlexOfferRevocationResponse + + + + + Result=Rejected + + + + + + + + + + + + + + + + + HTTP + + + + + OK + + + + + + + + + + + + + + + FlexOfferRevocationResponse + + + + + Result=Accepted + + + + + + + + + + + + + + + + + HTTP + + + + + OK + + + + + + + + diff --git a/specifications/3.0.0/docs/assets/images/use-case-3-9-revocation-of-flexoffer.svg.license b/specifications/3.0.0/docs/assets/images/use-case-3-9-revocation-of-flexoffer.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.0.0/docs/assets/images/use-case-3-9-revocation-of-flexoffer.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.0.0/docs/general-description/contract-phase.md b/specifications/3.0.0/docs/general-description/contract-phase.md new file mode 100644 index 00000000..52c6faa2 --- /dev/null +++ b/specifications/3.0.0/docs/general-description/contract-phase.md @@ -0,0 +1,121 @@ + + +# Contract phase + +## Overall description + +The contract phase is when DSOs and AGRs begin interaction. +Typically, this involves a pre-qualification process, where the AGRs capability to deliver flexibility, portfolio and IT systems are assessed. +AGR pre-qualification is out-of-scope for UFTP and therefore not further described in this document. +See [^B6] for more information. +In addition, the contract phase includes the exchange of information related to congestion points and associated connections through the common reference. +Note that any contract negotiations for bilateral contracts also takes place in the contract phase (see below). + +[^B6]: USEF, "Recommended practices and key considerations for a regulatory framework and market design on explicit Demand Response," 2017. [Online]. Available: [https://www.usef.energy/app/uploads/2017/09/Recommended-practices-for-DR-market-design-2.pdf](https://www.usef.energy/app/uploads/2017/09/Recommended-practices-for-DR-market-design-2.pdf). + +
+ ![General information flow in the Contract phase](../assets/images/image7.emf.odg.svg){ width=1000px } +
General information flow in the Contract phase
+
+ +As part of its internal grid planning process, a DSO determines where congestion may possibly take place. +Congestion points are declared whenever necessary, most likely several times a year, depending on the volume of trend analyses performed by a DSO and the condition of the grid. +By publishing a particular congestion point, the DSO opens a flexibility market for it. +AGRs publish the customers that they serve in the common reference. +As a result, a DSO can determine whether there is liquidity on its market and AGRs know which of their customers can participate in a DSO’s market. + +USEF introduces two alternative options for the DSO to procure flexibility from AGRs: + +- **Long-term flexibility options:** activation of flexibility options in prearranged bilateral contracts. +Contracts of this nature oblige the AGR to offer a fixed amount of flexibility to the market via daily FlexOffers. +This product guarantees a certain regular availability of flexibility but the price (model) has to be arranged in advance. +As a result, the DSO can select the contract(s) that provide the required flexibility at the lowest costs although these, typically, will not reflect all flexibility available in the market or the actual marginal costs for any flexibility supplied. +This method is comparable to the way in which national TSOs contract balancing services and a tender or auction procedure can be implemented to manage it, alongside long-term flexibility options subject to prearranged specific conditions; e.g. which include a maximum or fixed price for the activation of the flexibility. + +- **Short-term flexibility options:** procuring flexibility that AGRs have offered for a specific day. +In this situation, the AGR has no contractual obligation to offer the flexibility to the market but decides to do so on a day-to-day basis. +This product inherently deals with short-term flexibility which is only valid for a specific day. +The price offered by AGRs will better reflect the marginal costs although the availability of the flexibility in this product is not guaranteed. +This method is comparable with the way market parties are free to offer capacity to the TSO on the secondary and tertiary markets (regulating and reserve power) on a daily basis. + +The first option seems attractive for the DSO as it guarantees a minimum supply of flexibility, therefore reducing availability risks in the validate phase, but this comes at a higher price. +The DSO is responsible for finding the right balance between costs and certainty, while ensuring that grid reliability is always maintained. +It is important to note that both products are part of the same flexibility market and therefore it provides natural growth options for the evolution of flexibility trading. +While, initially, the availability of flexibility supply and demand might be a primary concern for both buyers and sellers, leading them to focus on long-term contracts, this will likely change as the market matures and availability becomes less of an issue. +At that point, both buyers and sellers would be willing to have greater reliance on short-term flexibility which, in turn, would offer increased market liquidity. + +## Bilateral contract: FlexOption + +For long-term flexibility, USEF introduces the **FlexOption**. This type of contract enables the DSO to take an option on future flexibility. In relation to this, USEF specifies that: + +- a FlexOption is a bilateral contract between DSO and AGR to deliver a specified amount of flexibility, at a specific location (i.e. congestion point), for a specified time schedule and duration. +- FlexOptions force the AGR to send flexibility offers when the flexibility requests match the contract details. +- FlexOptions are tradable via secondary markets. + +!!! success "Recommended practice:" + + In order to make FlexOptions attractive to AGRs, a DSO could add remuneration components; e.g. availability remuneration and/or a minimum number of activations. + +A FlexOption contract typically has the following ingredients: + +| Element | Description | Example(s) | +|-------------------------------|----------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------| +| ISPs and durations | The Imbalance Settlement Period (ISP) in which the flexibility should be delivered and the duration of the contract. |
  • Every ISP between 17:00 and 19:00 on Fridays
  • from December through March for the coming two years
| +| Lead time | Time before the (recurring) flexibility option expires. |
  • One week before dispatch
  • The day before dispatch at 16:00
  • Does not expire
| +| Congestion Point | DSO-specific: Congestion Point at which the flexibility should be realized. | | +| Amount | Amount of flexibility being offered, specified as a delta to a baseline value or drop to mechanism. |
  • 10kW (average power per ISP)
| +| Capacity remuneration | Price the AGR receives for offering the flexibility option |
  • €20/MW/day
  • €40/MW/ISP
| +| Volume remuneration | Maximum or predefined price for the flexibility, to be paid when the flexibility is ordered by the DSO. |
  • €20/MWh
  • Less than €20/MWh
  • €0
| +| Maximum number of activations | The Maximum number of activations at which the flexibility in the LT contract can be called upon. |
  • Once per contract
  • Once per month
  • Unlimited
| +| Recovery Time | Minimum time between activiations | | +| Penalties | Amount the AGR is penalized for not offering the option of flexibility and/or the flexibility itself. | n/a | + +UFTP does not include messages to communicate the contents of a FlexOption; this is assumed to be out-of-scope. + +## Common Reference + +A DSO declares its congestion points in the contract phase. +An AGR must be able to retrieve information about these points since this allows it to fulfil its obligation to provide the compulsory D-prognoses to DSOs for congestion points at which it represents customers. +It also aids the AGRs portfolio optimization activities. + +Since a prosumer can switch AGRs, and the congestion points in the grid change over time, USEF introduces a ‘common reference’. +The common reference contains a list of connection identifiers (for example EANs) for each congestion point, as registered by the participating DSOs. +Each AGR also registers the connections on which it represents prosumers. +The common reference is shared between all involved parties, while respecting privacy and security principles [^B5] which ensures, amongst other things, that only necessary information is shared and therefore included in the common reference. +The common reference is operated by the Common Reference Operator (CRO) role. +Conceptually, it contains the entities and relationships shown in the figure below: + +[^B5]: USEF Foundation, "USEF: The Privacy and Security Guideline," USEF Foundation, Arnhem, 2015. Available: [https://www.usef.energy/app/uploads/2016/12/USEF_PrivacySecurityGuideline_3nov15.pdf](https://www.usef.energy/app/uploads/2016/12/USEF_PrivacySecurityGuideline_3nov15.pdf) + +
+ ![Logical structure of the Common Reference](../assets/images/image8.emf.odg.svg){ width=1000px } +
Logical structure of the Common Reference
+
+ +The common reference is, typically, setup by the DSO and includes all of its congestion points. +However, it could be extended to form a common reference at national or European grid level. + +UFTP allows for the registering and tracking of changes in the common reference; e.g. a DSO might announce a new congestion point for the following week which is registered in the common reference. +The history of all changes to the common reference is retained and can be retrieved for a certain date using the query function functions (see [AGRPortfolioQuery](../message-descriptions/message-catalog/agr-portfolio-query.md) and [DSOPortfolioUpdate](../message-descriptions/message-catalog/dso-portfolio-update.md)); this will also help resolve any potential disputes. + +### Accessibility of the data in the common reference + +Access to the common reference data is limited according to the legal or contractual requirements of the various parties consulting it[^3]. +This implies that a DSO can only see the data for the connections it is responsible for. +Consequently, it can see which AGRs are serving its connections, in order to ensure that it receives D-prognoses from them. + +AGRs can only see information about the congestion points for which they serve connections. +In addition, they can retrieve the number of connections per congestion point. +Implementing the common reference this way ensures that the DSO does not need to share details of its grid topology. + +The common reference can be operated in two modes: open mode and closed mode. +If operating in open mode, the CRO will accept updates from any USEF-compliant participants. +In closed mode, participants will need to be pre-configured in order for updates to be accepted. + +[^3]: + Another option is to treat the common reference as open data, therefore implying that everyone can access it. + Although the open data model can ease the implementation of the common reference, the acceptance of such a model by prosumers is highly dependent on the culture in the geographical area in which the model is used. diff --git a/docs/general-description/index.md b/specifications/3.0.0/docs/general-description/index.md similarity index 100% rename from docs/general-description/index.md rename to specifications/3.0.0/docs/general-description/index.md diff --git a/specifications/3.0.0/docs/general-description/operate-phase.md b/specifications/3.0.0/docs/general-description/operate-phase.md new file mode 100644 index 00000000..0e9fb3ea --- /dev/null +++ b/specifications/3.0.0/docs/general-description/operate-phase.md @@ -0,0 +1,39 @@ + + +# Operate phase + +While (similar to the current liberalized energy market) the total energy system will remain in balance, without any congestion issues, as long as there are no deviations from the plans, it is unlikely that all plans will be executed exactly. +Deviations can arise from a range of sources, ranging from changing weather expectations to an extension of a football match. +Deviations can lead to: imbalances in supply and demand of energy at total system level (affecting the BRP); changes within the AGR portfolio (affecting the AGR); and local congestion in the distribution system (affecting the DSO). +USEF’s MCM is designed such that, during the operate phase, additional flexibility can be applied in order to compensate for these deviations. +The processes for invoking this flexibility are depicted in the following figure. + + + +
+ ![General information flows in the Operate phase.](../assets/images/image16.emf.odg.svg){ width=1000px } +
General information flows in the Operate phase.
+
+ +During the operate phase, the AGR’s main goal is to adhere to its plan and respect the D-prognoses.[^12] +In order to achieve this, FlexOfferRevocation the AGR must first plan to ensure assets operate in accordance with its forecast portfolio performance and that any flexibility sold is actually delivered. + +[^12]: UFTP allows for alternative baselines, see [General description](index.md). In case of alternative baselines, D-prognosis is optional. + +Next, the AGR measures the net demand or supply of its portfolio, in order to detect deviations from its plan and D-prognoses. +Where deviations occur, the AGR re-optimizes its portfolio. +It is possible that deviations could be solved using the flexibility contained within the portfolio itself. + +If this is not the case, the AGR must change its plan (and probably limit its liabilities due to non-performance, to minimize fines) and control the assets to ensure that the new plans are realized and send an updated D-prognosis. +If a FlexOffer has already been ordered, but the AGR is not able to comply, the AGR should inform the DSO as soon as possible through direct means outside of the UFTP protocol. +During the operate phase, the AGR may wish to revoke outstanding (i.e. not ordered) FlexOffers if it is no longer able or willing to deliver the flexibility. + +Although the DSO will reduce congestion risks in the validate phase, the DSO can still request that AGRs dispatch flexible power options to resolve potential grid problems in the operate phase. +Again, due to time constraints, this will be done based on flexibility offers from the validate phase, which are still valid. +When this flexibility is used, the corresponding BRP portfolio will no longer be in balance. +Where the AGR is responsible for the balance, it will most likely charge the additional costs to the DSO. +This is not considered further. diff --git a/specifications/3.0.0/docs/general-description/plan-phase.md b/specifications/3.0.0/docs/general-description/plan-phase.md new file mode 100644 index 00000000..bbff3925 --- /dev/null +++ b/specifications/3.0.0/docs/general-description/plan-phase.md @@ -0,0 +1,31 @@ + + +# Plan phase + +USEF’s plan phase aims to find an economically optimized program to supply the energy demand of both AGR and BRP portfolios for a certain period. +In this phase, the AGR optimizes its portfolio and typically arbitrages between different flexibility markets to maximize the value of the available flexibility. +The result of this process is a balanced portfolio. +The exchange between AGR and BRP’s and corresponding trades on the energy markets are out-of-scope for UFTP. +The result, however, will lead to a D-prognosis in the validate phase. + +The processes that take place during the plan phase are schematically depicted in the following figure. + +
+ ![General information flow in the Plan phase](../assets/images/image9.emf.odg.svg){ width=1000px } +
General information flow in the Plan phase
+
+ +Since the list of connections belonging to a congestion point, and the list of customers that are served by the AGR, may switch from day to day, USEF specifies that this information is requested on a day-to-day basis. + +The AGRs portfolio optimization is out-of-scope and depicted only for reference. +See [^3] for a detailed description of this process. +For UFTP, it is important to realize that the AGR optimizes its portfolio based on its clients’ needs, optionally taking into account its long-term contractual obligations. + +For bilateral contracts, the DSO might provide a FlexReservationUpdate message e.g. signaling which part of the contracted volume is still reserved and which part is not needed and may be used for other purposes. +This will typically re-trigger the AGRs portfolio optimization process. More information about the flex reservation mechanism is added in [Rationale for information exchange in flexibility request](../appendix/rationale-for-information-exchange-in-flexibility-request.md). + +[^3]: USEF, "USEF - The FrameWork Specifications 2015," 2015. [Online]. diff --git a/specifications/3.0.0/docs/general-description/settle-phase.md b/specifications/3.0.0/docs/general-description/settle-phase.md new file mode 100644 index 00000000..f89bb091 --- /dev/null +++ b/specifications/3.0.0/docs/general-description/settle-phase.md @@ -0,0 +1,137 @@ + + +# Settle phase + +## Overall description + +In the settle phase, the AGR is remunerated for the delivered flexibility. +There should be a check first, to ensure that the procured flexibility was actually delivered. +A penalty may be applied when there is a mismatch between the baseline and the actual profile. +Except for metering data, USEF assumes that both AGR and DSO have all the information to make these calculations. +The DSO sends its calculation to the AGR for verification. + +
+ ![General information flow flex settlement between DSO and AGR](../assets/images/image17.emf.odg.svg){ width=1000px } +
General information flow flex settlement between DSO and AGR
+
+ +In order to perform the settlement, it is necessary for the DSO to compare the metering for each ISP against the baseline, as contained in the demand-prognosis message. +In some regions the metering for the ISP periods for the fiscal meter may already be available to the DSO, through its own systems. +However, where the DSO does not have access to the meter data, or where plant metering is used for settlement assessment, the metering data must be communicated to the DSO by the AGR. +For this purpose the AGR will use the Metering messages to send the daily metering per ISP from each connection point. + +**Recommended Practice:** It is recommended to the include the Power profile in the settlement messages. + +Each month, the DSO will calculate the flexibility settlement volumes and prices for each AGR according to the steps below. + +1. **Calculate procured flexibility**
+For each congestion point and ISP, both the volumes and prices of the acquired flexibility are collected. +2. **Gather Metering Data**
+This is done either based on the DSO’s own metering records or using the metering message +3. **Validate if baselines are met**
+This step is only performed where flexibility has been procured from the specific AGR, for a congestion point and ISP. +The deviation between the final forecast (taking into account all procured flexibility) and the realized profile is calculated. +4. **Calculate flex settlement volumes and prices**
+The settlement volumes and prices are calculated (see example below). +5. **Send settlement message to AGR**
+This shows, per month, the accumulated settlement volume, accumulated deviation from the agreed baselines, and accumulated settlement price (accumulated over the ISPs and the congestion points). + +The AGR will use its own information to do the same calculations + +1. **Calculate sold flexibility** (equivalent to 1) +2. **Validate if baselines are met** (equivalent to 2) +3. **Plausibility check** (equivalent to 3)
+The results are compared to the settlement message received from the DSO. + +If the difference in the previous plausibility check is within limits, the AGR sends an acknowledgement to the DSO. +If the difference exceeds predefined limits, the DSO’s calculation is disputed. +This is signaled via the SettlementResponseMessage. +The dispute process is not part of USEF. + +## Settlement details + +The DSO is responsible for settling the flexibility that it has acquired from the AGR. +Within this settlement, the DSO needs to check whether the acquired flexibility has been delivered according to the agreements. +Penalties can arise where agreements have not been met and this is considered an integral part of the settlement process. + +This section describes how the supply of flexibility from the AGR to the DSO is settled. +Several methods are possible, depending on how the flexibility is offered to the DSO and, more precisely, whether the DSO uses the mechanism of long-term and short- term flex options, and whether these flex options are rewarded, even if they are not exercised. +Passive contribution to constraint management may also be rewarded. + +Calculations are (in general) performed at ISP level, with settlement calculated over a one-month period. + +### Settlement components + +The settlement consists of five components: + +1. **Settlement of acquired flexibility**
+The DSO will acquire flexibility through the market mechanism if congestion is expected, either ahead of time (validate phase) or real-time (operate phase). +On average, the market price is determined by the equilibrium of demanded and offered flexibility (merit order). +Following the recommendation given in Section [Flexibility trading between the AGR and DSO](validate-phase.md#flexibility-trading-between-the-agr-and-dso), pay-as-bid pricing is used for individual settlements. +2. **Settlement of deviations from baselines**
+AGRs that have sold flexibility to the DSO need to limit their capacity to the value stated in the baseline, corrected for the sold flexibility. +A penalty is raised for each ISP where the agreed capacity has (on average) been exceeded. +The penalty is single sided, meaning that the AGR is allowed to deviate from its baseline as long as the deviation contributes to avoiding the grid constraint. +3. **[optional] Settlement of long-term flexibility options (bilateral contracts)**
+The DSO may acquire long-term flexibility options to ensure that congestion can be avoided at all times. +This may be necessary to justify a decision to delay or defer grid investments, or where grid constraints are expected in the (near) future. +The DSO will determine (e.g. through audits) that the AGR is always capable of providing the contracted flexibility (at contracted times). +4. **[optional] Settlement of short-term flexibility options (FlexOffers which are not procured)**
+When grid constraints are expected during the validate phase by the DSO, all AGRs are asked to place flexibility offers. +AGRs whose flexibility bids are accepted by the DSO are expected to meet their (adjusted) baselines. +However, it is just as important for the DSO that the other AGRs are also bound to their baselines. +To enforce and reward this, the DSO may also accept an option on the flexibility offered by the AGR, even if the bid is not accepted, to ensure the AGR will not jeopardize grid constraints by invoking its flexibility for other purposes. +The DSO will pay the AGR for the option, as this will put a constraint on the total capacity of the AGRs portfolio. +5. **[Optional] Settlement of passive contribution to constraint management**
+Possible reward for AGRs that passively support the management of grid constraints – either by staying below the agreed value expressed in their baselines or by reducing more power than agreed in the exercised flexibility bid. +This is specifically relevant if constraints have been resolved by passive contributions, where other AGRs have exceeded the agreed capacities. +In this situation, the passive contribution can be rewarded using the raised penalties (zero sum calculations). + +The settlement method implicitly assumes that each AGR has the motivation and capacity to produce high quality baselines. + +### Settlement calculations + +(numbers refer to the settlement components above) + +| Nr. | Amount | P = | Q = | Remark(s) | +|-------|------------|---------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **1** | P x Q | P = flexiblity fee | Q = power called ("Delivered Flex Quantity") | The flexibility fee is determined by the equilibrium of demanded and offered flexibility (flexibility market). | +| **2** | P x Q | P = excess penalty (asymmetrical, only applied when deviation has contributed to congestion) | Q = allocation – initial baseline – Σ FlexOrders ("Power Deficiency Quantity"), where allocation is the average realized power during the ISP | This penalty only applies to AGRs that have sold flexibility (for this ISP), and corresponds with not meeting the agreements of the flexibility bid. | +| **3** | negotiated | n.a. | n.a. | The DSO will pay compensation for the long-term flexibility contract in proportion to the agreed power, the duration of the time slot, the nomination lead-time and the duration of the contract. Fixed fee may be derived from:
  • The costs for allowing thermal limitations to be violated;
  • The avoided costs for grid reinforcements;
  • The value of flexibility for alternative uses;
  • The costs of alternative flexibility options.
| +| **4** | P x Q | P = flexibility option fee | Q = power option | In this settlement component, an AGR can be rewarded for participating in the flexibility market through short-term products. Rationale for relating the flexibility option settlement to the capacity offered is that an option to cap the capacity of an AGR with twice the capacity of another AGR, has twice the value to the DSO. | +| **5** | P x Q | P = contribution fee (asymmetrical, only applied when deviation has relieved congestion). Derived from excess penalties raised. | Q = allocation - baselines – power flexibility called during Operate phase where allocation is the average realized power during the ISP. | | + +### Settlement example + +For a specific ISP we assume: + +- The AGR has specified a total load of 10 MW in its initial baseline +- During one or more flexibility requests, a total of 2 MW of flexibility has been acquired by the DSO, yielding an adjusted baseline of 8 MW +- The table below shows how different realizations are settled. The realization is specified by the allocation, representing the average power during one specific ISP for one congestion point. In this example the following (illustrative) prices are applied: + - Flex price equals 7 € / MW + - Baseline deviation penalty equals 11 € / MW (single sided) + +| Allocation (MW) | Flex realized (MW) | Delivered flex quantity (MW) | Flex paid (€) | baseline deviation (MW) | Power deficiency quantity (MW) | Penalty raised (€) | Settlement (€) | +|-----------------|--------------------|------------------------------|---------------|-------------------------|--------------------------------|--------------------|----------------| +| 7 | 3 | 2 | 14 | -1 | 0 | 0 | 14 | +| 8 | 2 | 2 | 14 | 0 | 0 | 0 | 14 | +| 9 | 1 | 1 | 7 | 1 | 1 | -11 | -4 | +| 10 | 0 | 0 | 0 | 2 | 2 | -22 | -22 | +| 11 | -1 | 0 | 0 | 3 | 3 | -33 | -33 | + +Elaboration of the calculations performed in the table: + +1. _Allocation_ shows possible results of the realization of the AGR portfolio +2. The _flex realized_ equals the baseline associated with the flex offer minus the allocation +3. The delivered _flex quantity_, represents the flexibility that is both acquired (therefore maximum of 2) and delivered. +Passive contributions (as in the row with allocation=7) are not rewarded. +4. The _flex paid_ equals the _delivered flex quantity_ times the flex price +5. The _baseline deviation_ equals the allocation minus the adjusted baseline +6. The _power deficiency quantity_ equals the _baseline deviation_, where negative deviations are set to 0 since these are not penalized. +7. The _penalty raised_ equals the _power deficiency quantity_ times the penalty +8. The settlement price equals the sum of the _flex paid_ and _penalties raised_. +9. The monthly totals of the elements: _delivered flex quantity, power deficiency quantity and Settlement_ are sent to the AGR. diff --git a/docs/general-description/usef-general-concepts.md b/specifications/3.0.0/docs/general-description/usef-general-concepts.md similarity index 100% rename from docs/general-description/usef-general-concepts.md rename to specifications/3.0.0/docs/general-description/usef-general-concepts.md diff --git a/specifications/3.0.0/docs/general-description/validate-phase.md b/specifications/3.0.0/docs/general-description/validate-phase.md new file mode 100644 index 00000000..df014794 --- /dev/null +++ b/specifications/3.0.0/docs/general-description/validate-phase.md @@ -0,0 +1,270 @@ + + +# Validate phase + +## Overall description + +
+ ![General information flow in Validate phase.](../assets/images/image10.emf.odg.svg){ width=1000px } +
General information flow in Validate phase
+
+ +Assuming that D-prognoses are used as baseline[^4], each AGR creates a D-prognosis per declared congestion point and sends it to the DSO. +Sending D-prognoses is not required when an alternative baseline method has been agreed. +When all D-prognoses for a congestion point are received, the DSO combines these with the forecasts of non-AGR connections to execute a final grid safety analysis. +This analysis determines whether it is possible to distribute the planned energy, or the limits of the distribution grid are reached. +In the latter situation, USEF moves to the yellow regime and the DSO procures flexibility in the market to resolve these congestion issues. +The process of flexibility trading is as follows: + +[^4]: + UFTP allows for alternative baselines, see [General description](index.md). + In case of alternative baselines, D-prognosis is optional. + +1. The DSO requests all AGRs at the congestion point to provide flexibility. +In this request, the DSO indicates the magnitude (amount of excess power) and timing (ISP) of the expected congestion, and how much capacity is available in the remaining ISPs. This is handled via a _FlexRequest_. +2. AGRs who are able and willing to change their load/generation profile in line with the request create _FlexOffers_. +3. If the offers are a good fit; i.e. help to mitigate congestion, the DSO can procure flexibility by placing a _FlexOrder_. +4. AGRs send an updated D-prognosis which incorporates the flexibility ordered. + +If the flexibility offered is not sufficient to resolve the expected congestion, or no flexibility is offered, USEF moves to the orange regime. +Please note that in this situation, USEF specifies that the DSO procures all offered flexibility from the market (i.e. from the yellow regime) to solve parts of the congestion. +This is because any flexibility offered will still help to reduce the impact of the orange regime (e.g. the number of connections impacted by the graceful degradation). +USEF’s orange regime is outside the scope of UFTP, and, therefore, not further discussed in this document. + +
+ ![AGR may send multiple FlexOffers on the same request, and open FlexOffers, which are not yet ordered may be revoked by the AGR.](../assets/images/image11.emf.odg.svg){ width=1000px } +
AGR may send multiple FlexOffers on the same request, and open FlexOffers, which are not yet ordered may be revoked by the AGR.
+
+ +AGRs may respond with one or more FlexOffers. +Where an AGR responds with multiple FlexOffers, the DSO can freely choose the most appropriate offer(s). +Provided the flexibility has not been ordered via a FlexOrder, a FlexOffer may be revoked by the AGR (FlexOfferRevocation). + +
+ ![Flexibility trading may go on until gate closure time. This includes iterations between plan phase and validate phase. The last accepted D-prognosis before gate closure time serves as a basis for the next phase. Any open FlexOffers, which are not expired, may be ordered after gate closure.](../assets/images/image12.emf.odg.svg){ width=1000px } +
Flexibility trading may go on until gate closure time. This includes iterations between plan phase and validate phase. The last accepted D-prognosis before gate closure time serves as a basis for the next phase. Any open FlexOffers, which are not expired, may be ordered after gate closure.
+
+ +## Exchange of D-prognoses between AGR and DSO + +When using D-prognoses as the baseline methodology, an AGR sends its D-prognosis per congestion point to the DSO. +The DSO assesses the validity of each received D-prognosis and informs the AGR whether or not it is accepted. +As long as the gate closure time has not passed, the AGR can update its D-prognoses and resend it to the DSO. +During these iterations, an accepted D-prognosis[^5] is assumed actual, provided no associated updates are received and accepted by the DSO. + +For the exchange of D-Prognoses, USEF specifies the following: + +- An AGR is obliged to create a D-prognosis for its connections as soon as its connection point is declared by a DSO. +The AGR is informed of this congestion point via the mandatory (daily) CRO queries. +- The D-prognosis only includes the forecasted load of those prosumers served by the AGR and that have a connection related to a congestion point. +- The D-Prognosis contains one full calendar day for the day-ahead process. +In the intraday process, all remaining ISPs for that calendar day must be included +- The average power is given per ISP as a minimum time granularity +- The D-Prognosis does not include additional information; e.g. details about the available flexibility or prices + +!!! success "USEF provides the following recommended practices for the exchange of D-Prognoses:" + + - The D-Prognosis is sent day-ahead to the DSO; at the latest, two hours before the gate closure of the national balancing regime (day-ahead gate closure)[^6] + - The DSO can perform a monthly evaluation of the accuracy and reliability of D-prognoses in order to motivate AGRs to improve the D-prognoses they supply + +[^5]: The accepted D-prognosis is the D-prognosis that used as a basis for the next period (Intraday) or phase (operate). +[^6]: For the difference between day-ahead and intraday, please refer to [Iterations between the plan and validate phases](validate-phase.md#iterations-between-the-plan-and-validate-phases) + +## Processing D-prognoses + +When all D-prognoses relating to a particular congestion point are received, the DSO creates a total prognosis for each congestion point. +When accumulating the D-prognoses, the DSO must estimate and add the distribution requirements required for those connections which are not served by an AGR, and, therefore, not included in the D-prognoses. +Using the accumulated D-prognosis, the DSO can determine whether it is possible to distribute the planned energy, or whether the limits of the distribution grid will be reached. + +The timing of the FlexRequest is determined by the DSO, who must make a trade-off between waiting for all AGRs to send their D-prognoses[^7] before identifying grid constraints or issuing a FlexRequest based on its own grid forecasting process. +It is the DSO’s responsibility to combine the two sources of information. +Where alternative baseline methods are used, the DSO will issue a FlexRequest based solely on its own information. + +[^7]: + USEF 2015 specified that the DSO should wait for all D-prognoses to be submitted. + This would allow for a more precise determination of possible congestion and also ensure a fair process of offering and procuring flexibility. + However, this constraint hinders the process in situations where there are missing or late D-prognoses. + +The grid safety analysis can lead to either of the following conclusions: + +- That no congestion is expected. All power flows are within calculated safety margins. +- That congestion is expected as the energy flows exceed calculated safety margins. The DSO then starts the process of acquiring flexibility from the market. + +Where no AGRs are active at the congestion point, there is no market to supply the DSO with flexibility to reduce its energy flows to levels below the safety margins. +In this situation, the system moves to the orange regime. +The resulting DSO processes are outside the scope of this document. +See [^B4] for a global description. + +## Flexibility trading between the AGR and DSO + +If the outcome of the grid safety analysis is that congestion will arise, the system is moved to the yellow regime and the DSO will need to take action. +In order to solve the expected congestion, the following steps are taken: + +1. The DSO requests all AGRs at the congestion point to provide flexibility. +In its request, the DSO indicates the magnitude (amount of excess power) and timing (ISP) of the expected congestion and (optionally) how much capacity is available in the remaining ISPs +2. The AGRs receive the flexibility request for adjusting[^8] distribution requirements +3. AGRs generate offers for the flexibility. Note that these offers could either be the result of a voluntary offering process or compulsory, where there are prearranged bilateral contracts between DSO and AGR (FlexOptions) +4. The DSO receives the flexibility offers +5. The DSO procures flexibility to resolve the congestion issues by placing flexibility orders. +6. The DSO determines whether the expected congestion is solved using the ordered flexibility. +If this is not the case, the system moves to the orange regime (see [^B4] for more details) +7. The AGRs receive the flexibility orders which result in the actual procurement of flexibility by the DSO. +8. AGRs provide an (updated) D-prognosis, incorporating the ordered flexibility. +This step only applies when D-prognoses are used as baseline methodology. + +[^B4]: USEF Foundation, "USEF: The Framework Explained," USEF Foundation, Arnhem, 2015. + +[^8]: Either by decreasing energy use, increasing local generation, or time-shifting load. + +When trading via a market platform AGRs typically offer their flexibility without an underlying request (unsolicited flex offers) and the DSO selects appropriate offers. +Steps 1 and 2 are not applicable in this situation. + +- Information about expected congestion is provided to all registered AGRs; +- Expected congestion information includes the direction of the overload (production/consumption); +- Expected congestion information includes the amount of reduction needed; +- Expected congestion information includes available grid capacity for other ISPs. + +See [Rationale for information exchange in flexibility request](../appendix/rationale-for-information-exchange-in-flexibility-request.md) for more details about this information exchange including rationale. + +In the [FlexRequest messages](../message-descriptions/message-catalog/flex-request.md), there is no single power value, rather a power space for each ISP, bound by two power values (“MinPower” and “MaxPower”). +In addition, there is a distinction between ISPs with a ‘requested’ disposition – meaning that there is a request for a deviation on the power consumption/production – and ISPs with an ‘available’ disposition – meaning that there is available space to deviate on the power consumption/production. + +
+ ![Example forecast for a Congestion point, leading to an example FlexRequest, both displayed in graphs](../assets/images/image13.svg){ width=1000px } +
Example forecast for a Congestion point, leading to an example FlexRequest, both displayed in graphs
+
+ +In the example used in the figure above, congestion is expected at ISP 2 at a certain congestion point. +The FlexRequest is transmitted to all AGRs that have prosumers on the congestion point, requesting a decrease of consumption (or an increase of production) on ISP 2. +If AGRs choose to shift consumption from ISP 2 to another ISP, the available spaces in the ISPs from the FlexRequest indicate that there is more room for consumption in ISP 5 than in ISP 1, 3 and 4. +A flexibility offer with a consumption shift to ISP 5 is therefore more likely to be ordered. + +Note that a request is always relative to the agreed baseline. +The essence of broadcasting the same request to all AGRs is that the requested deviation is the same for each AGR, relative to its own baseline. +Decreasing power consumption is thereby equivalent to increasing power production and vice versa. + +The distribution of the FlexRequest message is limited to AGRs which are registered via the CRO (see [Plan phase](plan-phase.md)). +The information on direction, amount and available capacity is provided in specific data structures that are part of the FlexRequest message (see [Power](../message-descriptions/message-catalog/power.md)). + +For the procurement of flexibility by the DSOs, USEF specifies the following rules: + +- A flexibility offer is valid until it expires or is revoked. +It is the AGRs responsibility to determine the acceptance deadline. +Revocation is not possible after the offer has been ordered. +- A flexibility order is definite and binding once it has been placed. +- The DSO chooses which flexibility offers it accepts to solve the congestion. +In this regard, it is not obligatory for the DSO to start with the offer that has the lowest price. +The DSO has the freedom to assess the balance between the price and quality[^9] of the flexibility offered in both long-term contracts and short-term offers. +- Bidding takes place at congestion point level, making every congestion point a local flexibility market. +- The DSO sends a flexibility request when the result of the grid safety analysis indicates possible congestion. +- A flexibility order is linked to a flexibility offer and a baseline for settlement purposes. + +[^9]: For example, it is desirable for the DSO to procure flexibility that moves energy use from a moment in time of high load to a moment in time of very low load, rather than procuring flexibility that moves energy use from a moment in of high load to a moment in time at which the maximum of the distribution capacity is almost reached. + +UFTP has two optional structures in the trading messages: + +- [optional] A FlexOffer can contain multiple mutually exclusive options. +The DSO is able to pick one of the options in its FlexOrder. +Whether or not an AGR is allowed to add multiple options is signaled in the CRO. + +- [optional] AGRs may indicate the capability for partial activation in their offers. +In all messages, a minimum activation percentage is provided i.e. all values lower than 100% mean that partial activation is possible. +The DSO could use partial activation to better match the requested flexibility with available offers. +Partial activation applies to all ISPs in the offer and also to the offered price. +For example, if the DSO procures 80% of the offer, all ISPs in the FlexOrder should be 80% of the corresponding ISPs in the FlexOffer, and the settlement price is set to 80% of the original price in the offer. +If the DSO has not implemented the option, it may simply ignore the structure. + +### Updates after flex has been ordered + +USEF specifies that when ISPs are altered as a result of a flexibility deal, the resulting load for these ISPs is used for settlement. +This means that deviation on ISPs with ‘requested’ disposition that have been traded, might lead to penalties for the associated AGR. +Updates on other ISPs are always possible for the AGR but will require a new D-prognosis. +Other AGRs can still change their D-prognoses for all ISPs without incurring a penalty. +More details about the penalty calculation can be found in the [settlement](settle-phase.md). + +The load profile resulting from a flexibility deal will be stored independently from any subsequent updates of the D-prognosis, because it allows the DSO to verify the actual delivery of the flexibility for settlement purposes. + +!!! success "Recommended Practice for flexibility trading:" + + For the procurement of flexibility by the DSOs, USEF recommends the following: + + - Publishing is in an anonymized way + - Pay-as-bid is used for pay-out. + - Timing of the flexibility orders is between 24 and 2 hours before delivery (day-ahead trading). + +## Iterations between the plan and validate phases + +As a result of flexibility exchange with the DSO, the AGRs portfolio is not balanced and so it may wish to re-optimize it. +By doing so, the MCM returns to the [plan phase](plan-phase.md), the only difference being that the AGR now takes the flexibility it has already sold into account. +In addition, during the plan phase, the AGR has the freedom to continuously re-optimize its portfolio whenever deemed necessary (e.g. when new and improved forecasts are available). +The rationale behind this high degree of freedom for the AGRs is to ensure that the flexibility they offer is applied in the most optimal and cost-effective way (i.e. flexibility is used there where it creates most value). + +However, these iterative processes also lead to the issue that D-prognoses change continuously, and continuous alignment is required between AGR/DSO. +As a result, there is a risk that the iterative process between the plan and validate phases does not converge. +In conclusion, there is a balance to be struck between making sure that the iterative processes converge, and offering a high degree of freedom to ensure that the available flexibility is used in the most optimal and cost-effective way. + +### Gate closure times + +For reasons mentioned above, USEF specifies that there needs to be at least two moments in time when the iterations are forced to end. This moment is called the gate closure time. + +In alignment with the current practices in liberalized energy markets, the two gate closure times are: + +1. Day-ahead closure time: the moment at which the day-ahead market closes. +During the day-ahead period, the plan and validate phases can be iterated as often as needed, as long as the system converges before the gate closure time. +After the day-ahead closure time, the processes in the plan phase can only be restarted during the intraday period. + +2. Intraday closure time[^10]: the moment at which the intraday market closes. +During the intraday period, the plan and validate phases can be iterated as often as needed, as long as the system converges before the gate closure time. +After the intraday closure time, the processes in the plan phase cannot be restarted at all, as the MCM moves to the operate phase. + +[^10]: Note that intraday flexibility trading is optional in UFTP so intraday gate closure applies only when intraday trading is enabled by the DSO + +
+ ![Example of USEF day-ahead gate closure time.](../assets/images/image14.emf.odg.svg){ width=1000px } +
Example of USEF day-ahead gate closure time.
+
+ +An example of the day-ahead gate closure is given in the figure above. +Please note that while there is a single day-ahead gate closure time per day, there will be multiple intra-day gate closures. +This is illustrated in the figure below. +The ISP corresponding to the current time is in operate phase and ISP’s more than one hour ahead are still in plan or validate phase. + +
+ ![Example of USEF intra-day gate closure times.](../assets/images/image15.emf.odg.svg){ width=1000px } +
Example of USEF intra-day gate closure times.
+
+ +!!! success "Recommended Practice:" + + The national regulator determines the specific timing details of the gate closures. USEF recommends: + + - A day-ahead gate closure time of 2 hours before the gate closure of the national balancing market + - An intraday gate closure time of one hour before the start of the ISP + +## Balance responsibility and redispatch options + +The procurement of flexibility by the DSO may impact the AGRs balance position (nomination)[^11]. +Therefore, USEF’s validate phase is iterative with the plan phase, i.e. the AGR can make adjustments to its nomination via energy exchange with its associated BRP and/or energy trades on the energy markets. +When the gate closure time is reached, all issues need to be resolved or there will be in an imbalance in the AGRs portfolio (which is the AGRs responsibility). + +[^11]: his is not the case when the AGR can manage the deviation itself, e.g. one prosumer uses more energy, another prosumer uses less energy, and these two level each other out. + +As an alternative, the procurement of flexibility is organized as an energy trade between AGR and DSO. +In this situation, the AGR portfolio stays balanced and there is no need to iterate to the plan phase. +Nevertheless, the AGR is free to re-optimize its portfolio at any time, for any reason, which could induce iterations. +The DSO faces imbalance as a result of the trade and is responsible for this. +The DSO’s imbalance can be restored via a counter trade outside the congested area (redispatch). + +USEF supports both ways of balance responsibility. +The DSO determines the method of trading for a given congestion point and signals this via the CRO. See [DSOPortfolioUpdate](../message-descriptions/message-catalog/dso-portfolio-update.md). + +!!! success "Recommended practices for balance responsibility:" + - USEF recommends that the AGR retains balance responsibility for day-ahead flexibility trading. + Any imbalance risk as a result of DSO trades can be mitigated via day-ahead energy trades. + - USEF recommends shifting the balance responsibility to the DSO for intraday flexibility trading. + This is equivalent to an energy trade from AGR to DSO. + In order to neutralize its position, the DSO should then trigger a counter-trade (redispatch). diff --git a/docs/index.md b/specifications/3.0.0/docs/index.md similarity index 100% rename from docs/index.md rename to specifications/3.0.0/docs/index.md diff --git a/specifications/3.0.0/docs/message-descriptions/message-catalog/agr-portfolio-query-response.md b/specifications/3.0.0/docs/message-descriptions/message-catalog/agr-portfolio-query-response.md new file mode 100644 index 00000000..60fc5811 --- /dev/null +++ b/specifications/3.0.0/docs/message-descriptions/message-catalog/agr-portfolio-query-response.md @@ -0,0 +1,57 @@ + + +# AGRPortfolioQueryResponse + +Upon receiving and processing an AGRPortfolioQuery message, the receiving implementation must reply with an AGRPortfolioUpdate, indicating whether the query was handled successfully. + +``` + + /> + + /> + /> + /> +/> +``` + +| | | +|----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see section [metadata attributes](metadata-attributes.md). | +| AGRPortfolioQueryMessageID | MessageID of the AGRPortfolioQuery message | +| Result | Indication whether the AGRPortfolioQuery was accepted or rejected. | +| RejectionReason | In case the AGRPortfolioQuery was rejected, this attribute must contain a human-readable description of the reason. | +| Period | The Period that the portfolio is valid. | +| DSO-View | | +| ⇥ DSO-Portfolio | Portfolio of a single DSO that shares connections with the AGR | +| ⇥ ⇥ DSO-Domain | The InternetDomain of the DSO the portfolio applied to. | +| ⇥ ⇥ CongestionPoint | A CongestionPoint that contains at least one Connection of a prosumer that is represented by the AGR. | +| ⇥ ⇥ ⇥ EntityAddress | Entity Address of the CongestionPoint entity being updated. | +| ⇥ ⇥ ⇥ MutexOffersSupported | Indicates whether the DSO accepts mutual exclusive FlexOffers on this CongestionPoint | +| ⇥ ⇥ ⇥ DayAheadRedispatchBy | Indicates which party is responsible for day-ahead redispatch, AGR or DSO. | +| ⇥ ⇥ ⇥ IntradayRedispatchBy | Indicates which party is responsible for intraday ahead redispatch, AGR or DSO. If not specified, there will be no intraday trading on this CongestionPoint. | +| ⇥ ⇥ ⇥ Connection | | +| ⇥ ⇥ ⇥ ⇥ EntityAddress | Entity Address of a Connection that is part of this CongestionPoint. | +| ⇥ ⇥ Connection | Connection not belonging to any DSO CongestionPoint | +| ⇥ ⇥ ⇥ EntityAddress | Entity Address of the Connection | diff --git a/docs/message-descriptions/message-catalog/agr-portfolio-query.md b/specifications/3.0.0/docs/message-descriptions/message-catalog/agr-portfolio-query.md similarity index 100% rename from docs/message-descriptions/message-catalog/agr-portfolio-query.md rename to specifications/3.0.0/docs/message-descriptions/message-catalog/agr-portfolio-query.md diff --git a/specifications/3.0.0/docs/message-descriptions/message-catalog/agr-portfolio-update-response.md b/specifications/3.0.0/docs/message-descriptions/message-catalog/agr-portfolio-update-response.md new file mode 100644 index 00000000..ae52dac4 --- /dev/null +++ b/specifications/3.0.0/docs/message-descriptions/message-catalog/agr-portfolio-update-response.md @@ -0,0 +1,25 @@ + + +# AGRPortfolioUpdateResponse + +Upon receiving and processing an AGRPortfolioUpdate message, the receiving implementation must reply with an AGRPortfolioUpdateResponse, indicating whether the update was handled successfully. + +``` + +``` + +| | | +|-----------------------------|----------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| AGRPortfolioUpdateMessageID | MessageID of the AGRPortfolioUpdate message | +| Result | Indication whether the AGRPortfolioUpdate was accepted or rejected. | +| RejectionReason | In case the AGRPortfolioUpdate was rejected, this attribute must contain a human-readable description of the reason. | diff --git a/docs/message-descriptions/message-catalog/agr-portfolio-update.md b/specifications/3.0.0/docs/message-descriptions/message-catalog/agr-portfolio-update.md similarity index 100% rename from docs/message-descriptions/message-catalog/agr-portfolio-update.md rename to specifications/3.0.0/docs/message-descriptions/message-catalog/agr-portfolio-update.md diff --git a/specifications/3.0.0/docs/message-descriptions/message-catalog/d-prognosis-response.md b/specifications/3.0.0/docs/message-descriptions/message-catalog/d-prognosis-response.md new file mode 100644 index 00000000..f05a2bce --- /dev/null +++ b/specifications/3.0.0/docs/message-descriptions/message-catalog/d-prognosis-response.md @@ -0,0 +1,33 @@ + + +# D-PrognosisResponse + +Upon receiving and processing a prognosis message, the receiving implementation must reply with a D-PrognosisResponse, indicating whether the prognosis was syntactically and semantically valid, and, where any FlexOrder messages have previously been sent for any ISP in the period the prognosis applies to, a FlexOrderStatus indication for each of those orders. + +``` + +/> +``` + +| | | +|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| D-PrognosisMessageID | Reference to the the D-prognosis that was accepted or rejected | +| Result | Indication whether the prognosis was accepted or rejected. A receiving implementation may reject a prognosis if it's syntactically invalid, uses a ISP duration or time zone that deviates from what is agreed upon for the market, is for a unknown Congestion Point or from an AGR that is not listed in the Common Reference, does not contain a full list of ISPs for the Period it applies to, contains implausible power values, applies to a Period for which all ISPs are already pending settlement, or if a Prognosis of the same type and from the same originator with a higher sequence number was already processed previously. | +| RejectionReason | In case the update was rejected, this attribute must contain a human-readable description of the failure. | +| FlexOrderStatus | Status of a previously submitted FlexOrder | +| ⇥ Sequence | Sequence of the previously submitted FlexOrder. | +| ⇥ IsValidated | Indication whether the Prognosis that was just received reflects this previously submitted FlexOrder. | + diff --git a/docs/message-descriptions/message-catalog/d-prognosis.md b/specifications/3.0.0/docs/message-descriptions/message-catalog/d-prognosis.md similarity index 100% rename from docs/message-descriptions/message-catalog/d-prognosis.md rename to specifications/3.0.0/docs/message-descriptions/message-catalog/d-prognosis.md diff --git a/specifications/3.0.0/docs/message-descriptions/message-catalog/dso-portfolio-query-response.md b/specifications/3.0.0/docs/message-descriptions/message-catalog/dso-portfolio-query-response.md new file mode 100644 index 00000000..d23de5a2 --- /dev/null +++ b/specifications/3.0.0/docs/message-descriptions/message-catalog/dso-portfolio-query-response.md @@ -0,0 +1,40 @@ + + +# DSOPortfolioQueryResponse + +Upon receiving and processing a DSOPortfolioQuery message, the receiving implementation must reply with a DSOPortfolioQueryResponse, indicating whether the query executed successfully, and if it did, including the query results. +Most queries will return zero or more congestion points + +``` + + /> +/> +``` + +| | | +|----------------------------|-----------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| DSOPortfolioQueryMessageID | MessageID of the DSOPortfolioQuery message | +| Result | Indication whether the query was executed successfully or failed. | +| RejectionReason | In case the query failed, this attribute must contain a human-readable description of the failure reason. | +| Period | The period that was queried. This is also the Period for which the portfolio is valid. | +| CongestionPoint | The congestion point that was queried. | +| ⇥ EntityAddress | The entity address of the congestion point. | +| ⇥ Connection | A Connection that is part of the congestion point. | +| ⇥ ⇥ EntityAddress | The entity address of the Connection | +| ⇥ ⇥ AGR-Domain | The internet domain of the AGR that represents the prosumer connected on this Connection, if applicable. | diff --git a/docs/message-descriptions/message-catalog/dso-portfolio-query.md b/specifications/3.0.0/docs/message-descriptions/message-catalog/dso-portfolio-query.md similarity index 100% rename from docs/message-descriptions/message-catalog/dso-portfolio-query.md rename to specifications/3.0.0/docs/message-descriptions/message-catalog/dso-portfolio-query.md diff --git a/specifications/3.0.0/docs/message-descriptions/message-catalog/dso-portfolio-update-response.md b/specifications/3.0.0/docs/message-descriptions/message-catalog/dso-portfolio-update-response.md new file mode 100644 index 00000000..b53830f7 --- /dev/null +++ b/specifications/3.0.0/docs/message-descriptions/message-catalog/dso-portfolio-update-response.md @@ -0,0 +1,25 @@ + + +# DSOPortfolioUpdateResponse + +Upon receiving and processing a DSOPortfolioUpdate message, the receiving implementation must reply with a DSOPortfolioUpdateResponse, indicating whether the update was handled successfully. + +``` + +``` + +| | | +|-----------------------------|----------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| DSOPortfolioUpdateMessageID | MessageID of the DSOPortfolioUpdate message | +| Result | Indication whether the DSOPortfolioUpdate was accepted or rejected. | +| RejectionReason | In case the DSOPortfolioUpdate was rejected, this attribute must contain a human-readable description of the reason. | diff --git a/docs/message-descriptions/message-catalog/dso-portfolio-update.md b/specifications/3.0.0/docs/message-descriptions/message-catalog/dso-portfolio-update.md similarity index 100% rename from docs/message-descriptions/message-catalog/dso-portfolio-update.md rename to specifications/3.0.0/docs/message-descriptions/message-catalog/dso-portfolio-update.md diff --git a/specifications/3.0.0/docs/message-descriptions/message-catalog/flex-offer-response.md b/specifications/3.0.0/docs/message-descriptions/message-catalog/flex-offer-response.md new file mode 100644 index 00000000..a9f9b6ac --- /dev/null +++ b/specifications/3.0.0/docs/message-descriptions/message-catalog/flex-offer-response.md @@ -0,0 +1,25 @@ + + +# FlexOfferResponse + +Upon receiving and processing a FlexOffer message, the receiving implementation must reply with a FlexOfferResponse, indicating whether the flexibility offer was processed successfully. + +``` + +``` + +| | | +|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| FlexOfferMessageID | MessageID of the FlexOffer that has been accepted or rejected. | +| Result | Indication whether the flex offer was accepted or rejected. Rejection is allowed in case no matching FlexRequest can be found, or the FlexOffer does not contain a valid price for each ISP with Disposition=Requested in the corresponding FlexRequest. | +| RejectionReason | In case the offer was rejected, this attribute must contain a human-readable description of the reason. | diff --git a/specifications/3.0.0/docs/message-descriptions/message-catalog/flex-offer-revocation-response.md b/specifications/3.0.0/docs/message-descriptions/message-catalog/flex-offer-revocation-response.md new file mode 100644 index 00000000..b3e6bbe4 --- /dev/null +++ b/specifications/3.0.0/docs/message-descriptions/message-catalog/flex-offer-revocation-response.md @@ -0,0 +1,25 @@ + + +# FlexOfferRevocationResponse + +Upon receiving and processing a FlexOfferRevocation message, the receiving implementation must reply with a FlexOfferRevocationResponse, indicating whether the revocation was handled successfully. + +``` + +``` + +| | | +|------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| FlexOfferRevocationMessageID | MessageID of the FlexOffer that a revocation message was received for. | +| Result | Indication whether the revocation was accepted or rejected. Rejection is allowed in case the FlexOffer is unknown (it is the responsibility of the sending party not to revoke FlexOffer messages that have not yet been accepted), or the offered flexibility has already been ordered. | +| RejectionReason | In case the revocation was rejected, this attribute must contain a human-readable description of the reason. | diff --git a/docs/message-descriptions/message-catalog/flex-offer-revocation.md b/specifications/3.0.0/docs/message-descriptions/message-catalog/flex-offer-revocation.md similarity index 100% rename from docs/message-descriptions/message-catalog/flex-offer-revocation.md rename to specifications/3.0.0/docs/message-descriptions/message-catalog/flex-offer-revocation.md diff --git a/specifications/3.0.0/docs/message-descriptions/message-catalog/flex-offer.md b/specifications/3.0.0/docs/message-descriptions/message-catalog/flex-offer.md new file mode 100644 index 00000000..f2362dc8 --- /dev/null +++ b/specifications/3.0.0/docs/message-descriptions/message-catalog/flex-offer.md @@ -0,0 +1,61 @@ + + +# FlexOffer + +FlexOffer messages are used by AGRs to make DSOs an offer for provision of flexibility. +A FlexOffer message contains a list of ISPs and, for each ISP, the change in consumption or production offered and the price for the total amount of flexibility offered. +FlexOffer messages can be sent once a FlexRequest message has been received but can also be sent unsolicited. +Note that multiple FlexOffer messages may be sent based on a single FlexRequest, e.g. to increase the chance that the DSO will order at least part of its available flexibility. +The AGR must make sure that it can actually provide the flexibility offered across all of its FlexOffers. + +``` + + /> +/> +``` + + +| | | +|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see section [metadata attributes](metadata-attributes.md). | +| Period | The Period the ISPs referenced in this FlexOffer message belong to. | +| CongestionPoint | Entity Address of the Congestion Point this FlexOffer message applies to. | +| ExpirationDateTime | Date and time, including the time zone (ISO 8601 formatted as per [http://www.w3.org/TR/NOTE-datetime](http://www.w3.org/TR/NOTE-datetime)) until when the FlexOffer message is valid. | +| FlexRequestMessageID | MessageID of the FlexRequest message this request is based on. | +| ContractID | Reference to the concerning bilateral contract, if applicable. | +| D-PrognosisMessageID | MessageID of the D-Prognosis this request is based on, if it has been agreed that the baseline is based on D-prognoses. | +| BaselineReference | Identification of the baseline prognosis, if another baseline methodology is used than based on D-prognoses. | +| Currency | ISO 4217 code indicating the currency that applies to the price of the FlexOffer. | +| OfferOption | If the DSO does not support mutually exclusive offers it will reject FlexOffers that contain more than one OfferOption. | +| ⇥ OptionReference | The identification of this option | +| ⇥ Price | The asking price for the flexibility offered in this option. | +| ⇥ MinActivationFactor | The minimal activation factor for this OfferOption. If this attribute is omitted, a default value of 1.00 must be assumed.
An AGR may choose to include MinActivationFactor in FlexOffers even if the DSO is not interested in partial activation. In that case the DSO will simply use an ActivationFactor of 1.00 in every FlexOrder. | +| ⇥ ISP | | +| ⇥ ⇥ Disposition | Optional, used only for FlexRequest messages: indication whether the Power specified for this ISP represents available capacity or a request for reduction/increase. | +| ⇥ ⇥ Power | Power specified for this ISP in Watts. Also see the important notes about the sign of this attribute in the main documentation entry for the ISP element, section [power](power.md). | +| ⇥ ⇥ Start | Number of the first ISP this element refers to. The first ISP of a day has number 1. | +| ⇥ ⇥ Duration | The number of the ISPs this element represents. Optional, default value is 1. | + + diff --git a/specifications/3.0.0/docs/message-descriptions/message-catalog/flex-order-response.md b/specifications/3.0.0/docs/message-descriptions/message-catalog/flex-order-response.md new file mode 100644 index 00000000..ea516e54 --- /dev/null +++ b/specifications/3.0.0/docs/message-descriptions/message-catalog/flex-order-response.md @@ -0,0 +1,25 @@ + + +# FlexOrderResponse + +Upon receiving and processing a FlexOrder message, the receiving implementation must reply with a FlexOrderResponse, indicating whether the update was handled successfully. + +``` + +``` + +| | | +|--------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| FlexOrderMessageID | MessageID of the FlexOrder that has just been accepted or rejected. | +| Result | Indication whether the order was accepted or rejected. Rejection is only allowed in case the FlexOrder was already accepted previously, cannot be found, or does not exactly match the contents of the corresponding FlexOffer. | +| RejectionReason | In case the order was rejected, this attribute must contain a human-readable description of the reason. | diff --git a/specifications/3.0.0/docs/message-descriptions/message-catalog/flex-order.md b/specifications/3.0.0/docs/message-descriptions/message-catalog/flex-order.md new file mode 100644 index 00000000..6456ee72 --- /dev/null +++ b/specifications/3.0.0/docs/message-descriptions/message-catalog/flex-order.md @@ -0,0 +1,52 @@ + + +# FlexOrder + +FlexOrder messages are used by DSOs to purchase flexibility from an AGR based on a previous FlexOffer. +A FlexOrder message contains a list of ISPs, with, for each ISP, the change in consumption or production to be realized by the AGR, and the accepted price to be paid by the DSO for this amount of flexibility. +This ISP list should be copied from the FlexOffer message without modification: AGR implementations will (and must) reject FlexOrder messages where the ISP list is not exactly the same as offered. + +``` + +/> +``` + +| | | +|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| Period | Period the ISPs referenced in this FlexOrder message belong to. | +| CongestionPoint | Entity Address of the Congestion Point this FlexOrder message applies to | +| FlexOfferMessageID | MessageID of the FlexOffer message this order is based on. | +| ContractID | Reference to the bilateral contract in question, if applicable. | +| D-PrognosisMessageID | MessageID of the D-Prognosis this order is based on, if present | +| BaselineReference | Identification of the baseline prognosis, if another baseline methodology is used than based on D-prognoses. | +| Price | The price for the flexibility ordered. Usually, the price should match the price of the related FlexOffer. | +| Currency | ISO 4217 code indicating the currency that applies to the price of the FlexOrder. | +| OrderReference | Order number assigned by the DSO originating the FlexOrder. To be stored by the AGR and used in the settlement phase. | +| OptionReference | The OptionReference from the OfferOption chosen from the FlexOffer. | +| ActivationFactor | The activation factor for this OfferOption. If this attribute is omitted, a default value of 1.00 must be assumed.
Notes:
The ActivationFactor must be greater than or equal to the MinActivationFactor in the OfferOption chosen from the FlexOffer. | +| ISP | | +| ⇥ Power | Power specified for this ISP in Watts. Also see the important notes about the sign of this attribute in the main documentation entry for the ISP element, section [power](power.md). | +| ⇥ Start | Number of the first ISP this element refers to. The first ISP of a day has number 1. | +| ⇥ Duration | The number of the ISPs this element represents. Optional, default value is 1. | diff --git a/specifications/3.0.0/docs/message-descriptions/message-catalog/flex-request-response.md b/specifications/3.0.0/docs/message-descriptions/message-catalog/flex-request-response.md new file mode 100644 index 00000000..0808aec7 --- /dev/null +++ b/specifications/3.0.0/docs/message-descriptions/message-catalog/flex-request-response.md @@ -0,0 +1,25 @@ + + +# FlexRequestResponse + +Upon receiving and processing a FlexRequest message, the receiving implementation must reply with a FlexRequestResponse, indicating whether the flexibility request was processed successfully. + +``` + +``` + +| | | +|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| FlexRequestMessageID | MessageID of the FlexRequest that has been accepted or rejected. | +| Result | Indication whether the flex request was accepted or rejected. Rejection is allowed in case the FlexRequest is not based on our latest Prognosis, a FlexRequest from the same participant for the indicated period with a higher sequence number was already accepted previously or the FlexRequest does not contain any ISPs with Disposition=Requested. | +| RejectionReason | In case the request was rejected, this attribute must contain a human-readable description of the reason. | diff --git a/docs/message-descriptions/message-catalog/flex-request.md b/specifications/3.0.0/docs/message-descriptions/message-catalog/flex-request.md similarity index 100% rename from docs/message-descriptions/message-catalog/flex-request.md rename to specifications/3.0.0/docs/message-descriptions/message-catalog/flex-request.md diff --git a/specifications/3.0.0/docs/message-descriptions/message-catalog/flex-reservation-update-response.md b/specifications/3.0.0/docs/message-descriptions/message-catalog/flex-reservation-update-response.md new file mode 100644 index 00000000..1cafe4f6 --- /dev/null +++ b/specifications/3.0.0/docs/message-descriptions/message-catalog/flex-reservation-update-response.md @@ -0,0 +1,25 @@ + + +# FlexReservationUpdateResponse + +Upon receiving and processing a FlexReservationUpdate message, the AGR must reply with a FlexReservationUpdateResponse, indicating whether the FlexReservationUpdate was processed successfully. + +``` + +``` + +| | | +|--------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see section [metadata attributes](metadata-attributes.md). | +| FlexReservationUpdateMessageID | MessageID of the concerning FlexReservationUpdate message | +| Result | Indication whether the FlexReservationUpdate was accepted or rejected. Rejection is allowed in case the FlexReservationUpdate does not match the bilateral contract or its agreements or the deadline for sending the update has expired. | +| RejectionReason | In case the request was rejected, this attribute must contain a human-readable description of the reason. | diff --git a/docs/message-descriptions/message-catalog/flex-reservation-update.md b/specifications/3.0.0/docs/message-descriptions/message-catalog/flex-reservation-update.md similarity index 100% rename from docs/message-descriptions/message-catalog/flex-reservation-update.md rename to specifications/3.0.0/docs/message-descriptions/message-catalog/flex-reservation-update.md diff --git a/specifications/3.0.0/docs/message-descriptions/message-catalog/flex-settlement-response.md b/specifications/3.0.0/docs/message-descriptions/message-catalog/flex-settlement-response.md new file mode 100644 index 00000000..7b7fa16d --- /dev/null +++ b/specifications/3.0.0/docs/message-descriptions/message-catalog/flex-settlement-response.md @@ -0,0 +1,58 @@ + + +# FlexSettlementResponse + +Upon receiving and processing a FlexSettlement message, the AGR must reply with a FlexSettlementResponse, indicating whether the initial message was handled successfully. +When a FlexSettlement message is rejected, the DSO should consider all FlexOrderSettlement elements of that message related to potential dispute. + +``` + + + /> + /> +/> +``` + +| | | +|---------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| FlexSettlementMessageID | MessageID of the FlexSettlement that has just been accepted or rejected | +| Result | Indication whether the message was accepted or rejected. Rejection is only allowed in case a FlexSettlement covering a given period was already accepted previously, or contains invalid data. If one or more settlement items included in the message are not in accordance with the AGR’s accounting, the message should still be accepted, and the dispute communicated using the appropriate FlexOrderSettlementStatus elements. | +| RejectionReason | In case the message was rejected, this attribute must contain a human-readable description of the reason. | +| FlexOrderSettlementStatus | Each FlexOrderSettlementStatus element indicates whether the settlement details about a FlexOrder, included in the corresponding FlexOrderSettlement element, are accepted or disputed by the AGR. | +| ⇥ OrderReference | Order reference assigned by the DSO when originating the FlexOrder. | +| ⇥ Disposition | Indication whether the AGR accepts the order settlement details provided by the DSO (and will invoice accordingly), or disputes these details. | +| ⇥ DisputeReason | In case the order settlement was disputed, this attribute must contain a human-readable description of the reason. | +| ContractSettlementStatus | Each ContractSettlementStatus element indicates whether the settlement details about a bilateral contract, included in the corresponding ContractSettlement element, are accepted or disputed by the AGR. | +| ⇥ ContractID | Reference to the concerning bilateral contract. | +| ⇥ Period | List of all periods from the ContractSettlement, including possible lacking periods | +| ⇥ ⇥ Period | Period the settlement status refers to. | +| ⇥ ⇥ ISP | | +| ⇥ ⇥ ⇥ Start | Number of the first ISP this element refers to. The first ISP of a day has number 1. | +| ⇥ ⇥ ⇥ Duration | The number of ISPs this element represents. It is recommended to merge consecutive ISPs with the same disposition. | +| ⇥ ⇥ ⇥ Disposition | Indication whether the AGR accepts the settlement details as provided by the DSO from the ISP(s) in question (and will invoice accordingly), or disputes these details. | +| ⇥ ⇥ ⇥ DisputeReason | In case the settlement from the ISP(s) was disputed, this attribute must contain a human-readable description of the reason. | + +Handling disputed settlement details is a manual process outside the UFTP scope. diff --git a/docs/message-descriptions/message-catalog/flex-settlement.md b/specifications/3.0.0/docs/message-descriptions/message-catalog/flex-settlement.md similarity index 100% rename from docs/message-descriptions/message-catalog/flex-settlement.md rename to specifications/3.0.0/docs/message-descriptions/message-catalog/flex-settlement.md diff --git a/docs/message-descriptions/message-catalog/index.md b/specifications/3.0.0/docs/message-descriptions/message-catalog/index.md similarity index 100% rename from docs/message-descriptions/message-catalog/index.md rename to specifications/3.0.0/docs/message-descriptions/message-catalog/index.md diff --git a/specifications/3.0.0/docs/message-descriptions/message-catalog/metadata-attributes.md b/specifications/3.0.0/docs/message-descriptions/message-catalog/metadata-attributes.md new file mode 100644 index 00000000..ed0061f3 --- /dev/null +++ b/specifications/3.0.0/docs/message-descriptions/message-catalog/metadata-attributes.md @@ -0,0 +1,33 @@ + + +# Metadata attributes + +The Metadata attributes contain metadata that are common for each non-wrapper USEF message. + +XML representation summary + +``` +SenderDomain = InternetDomain +RecipientDomain = InternetDomain +TimeStamp = DateTime +MessageID = UUID +ConversationID = UUID +ISP-Duration = Duration +TimeZone = TimezoneName +Version = SpecVersion +``` + +| | | +|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| SenderDomain | The Internet domain of the USEF participant sending this message. When receiving a message, its value should match the value specified in the SignedMessage wrapper: otherwise, the message must be rejected as invalid. When replying to this message, this attribute, combined with the SenderRole, is used to look up the USEF endpoint the reply message should be delivered to. | +| RecipientDomain | Internet domain of the participant this message is intended for. When sending a message, this attribute, combined with the RecipientRole, is used to look up the USEF endpoint the message should be delivered to. | +| TimeStamp | Date and time this message was created, including the time zone (ISO 8601 formatted as per [http://www.w3.org/TR/NOTE-datetime](http://www.w3.org/TR/NOTE-datetime)). | +| MessageID | Unique identifier (UUID/GUID as per IETF RFC 4122) for this message, to be generated when composing each message. | +| ConversationID | Unique identifier (UUID/GUID as per IETF RFC 4122) used to correlate responses with requests, to be generated when composing the first message in a conversation and subsequently copied from the original message to each reply message. | +| ISP-Duration | ISO 8601 time interval (minutes only, for example PT15M) indicating the duration of the ISPs referenced in this message. Although the ISP length is a market-wide fixed value, making this assumption explicit in relevant messages is important for validation purposes, allowing implementations to reject messages with an errant ISP duration.
Only messages that refer to individual ISPs must include this attribute in the metadata. | +| TimeZone | Time zone ID (as per the IANA time zone database, [http://www.iana.org/time-zones](http://www.iana.org/time-zones), for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in relevant messages is important for validation purposes, allowing implementations to reject messages with an errant UTC offset.
Only messages that refer to a specific Period must include this attribute in the metadata. | +| Version | Shapeshifter specification version following semantic versioning rules e.g. 3.0.0 | diff --git a/specifications/3.0.0/docs/message-descriptions/message-catalog/metering-response.md b/specifications/3.0.0/docs/message-descriptions/message-catalog/metering-response.md new file mode 100644 index 00000000..82124119 --- /dev/null +++ b/specifications/3.0.0/docs/message-descriptions/message-catalog/metering-response.md @@ -0,0 +1,25 @@ + + +# MeteringResponse + +Upon receiving and processing a Metering message, the receiving implementation must reply with a MeteringResponse, indicating whether the update was handled successfully. + +``` + +``` + +| | | +|-------------------|------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see section [metadata attributes](metadata-attributes.md). | +| MeteringMessageID | MessageID of the Metering message that has just been accepted or rejected. | +| Result | Indication whether the order was accepted or rejected. | +| RejectionReason | In case the metering was rejected, this attribute must contain a human-readable description of the reason. | diff --git a/docs/message-descriptions/message-catalog/metering.md b/specifications/3.0.0/docs/message-descriptions/message-catalog/metering.md similarity index 100% rename from docs/message-descriptions/message-catalog/metering.md rename to specifications/3.0.0/docs/message-descriptions/message-catalog/metering.md diff --git a/docs/message-descriptions/message-catalog/power.md b/specifications/3.0.0/docs/message-descriptions/message-catalog/power.md similarity index 100% rename from docs/message-descriptions/message-catalog/power.md rename to specifications/3.0.0/docs/message-descriptions/message-catalog/power.md diff --git a/docs/message-descriptions/message-catalog/signed-message.md b/specifications/3.0.0/docs/message-descriptions/message-catalog/signed-message.md similarity index 100% rename from docs/message-descriptions/message-catalog/signed-message.md rename to specifications/3.0.0/docs/message-descriptions/message-catalog/signed-message.md diff --git a/specifications/3.0.0/docs/message-descriptions/message-catalog/test-message-response.md b/specifications/3.0.0/docs/message-descriptions/message-catalog/test-message-response.md new file mode 100644 index 00000000..1cb9ce0b --- /dev/null +++ b/specifications/3.0.0/docs/message-descriptions/message-catalog/test-message-response.md @@ -0,0 +1,20 @@ + + +# TestMessageResponse + +Upon receiving a TestMessage, the receiving implementation must reply with a TestMessageResponse. +Like the TestMessage itself, the TestMessageResponse does not have any content (other than the mandatory metadata). + +``` + +``` + +| | | +|----------|------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | diff --git a/docs/message-descriptions/message-catalog/test-message.md b/specifications/3.0.0/docs/message-descriptions/message-catalog/test-message.md similarity index 100% rename from docs/message-descriptions/message-catalog/test-message.md rename to specifications/3.0.0/docs/message-descriptions/message-catalog/test-message.md diff --git a/specifications/3.0.0/docs/message-descriptions/scope.md b/specifications/3.0.0/docs/message-descriptions/scope.md new file mode 100644 index 00000000..a81efd89 --- /dev/null +++ b/specifications/3.0.0/docs/message-descriptions/scope.md @@ -0,0 +1,21 @@ + + +# Scope + +USEF defines the content of XML messages between role processes, as required for implementation of USEF’s MCM. +Each message has a unique recipient, identified by the Internet domain and USEF role of the participant. +The message transfer mechanism is responsible for sending and receiving these messages. + +
+ ![Relationship between the normative USEF XML messages (yellow pane) and the best-practice message transfer mechanism (light-blue pane).](../assets/images/image18.emf.odg.svg){ width=1000px } +
Relationship between the normative USEF XML messages (yellow pane) and the best-practice message transfer mechanism (light-blue pane).
+
+ +When selecting a message transfer mechanism, local market conditions should be considered and the USEF privacy and security guidelines should be followed [^B5]. +Further recommendations about the message transport mechanism are given in [Message transport mechanism](../appendix/message-transport-mechanism.md). + +[^B5]: USEF Foundation, "USEF: The Privacy and Security Guideline," USEF Foundation, Arnhem, 2015. Available: [https://www.usef.energy/app/uploads/2016/12/USEF_PrivacySecurityGuideline_3nov15.pdf](https://www.usef.energy/app/uploads/2016/12/USEF_PrivacySecurityGuideline_3nov15.pdf) diff --git a/docs/use-case-descriptions/common-concepts.md b/specifications/3.0.0/docs/use-case-descriptions/common-concepts.md similarity index 100% rename from docs/use-case-descriptions/common-concepts.md rename to specifications/3.0.0/docs/use-case-descriptions/common-concepts.md diff --git a/specifications/3.0.0/docs/use-case-descriptions/message-validation.md b/specifications/3.0.0/docs/use-case-descriptions/message-validation.md new file mode 100644 index 00000000..b960dc75 --- /dev/null +++ b/specifications/3.0.0/docs/use-case-descriptions/message-validation.md @@ -0,0 +1,37 @@ + + +# Message validation + +Incoming messages need to be validated by the recipient for their correctness. +Validation of the semantics is performed by the HTTP over TLS (explained in [Message transport mechanism](../appendix/message-transport-mechanism.md)), but the content still needs to be checked for possible discrepancies. +If the message passes validation, a response message is sent with ‘accepted’ in the result field. +If it fails validation, a response message is sent with ‘rejected’ in the result field, along with a description of the reason why the message is rejected in the RejectionReason field. +Some causes to reject a message are specific for the type of message and are mentioned in the remainder of this chapter. +Other causes are more generic and are listed in the table below. + +This list is not all-encompassing: stakeholders are allowed to formulate other reasonable causes to reject a message, as long as it is clearly explained in the RejectionReason field. +This field can contain multiple reasons for rejections (separated by a semicolon). + +| RejectionReason | Cause of rejection | +|----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Invalid Sender | Despite being schema-compliant, the syntax, type or semantics of the message were unacceptable for the receiving implementation. | +| Invalid Message | There is a mismatch between the SenderDomain/Role combination in the message wrapper and the inner XML message. | +| Unknown Recipient | The RecipientDomain and/or RecipientRole specified in the inner XML message is not handled by this endpoint. | +| Barred Sender | This endpoint is explicitly blocking messages from this sender. | +| Duplicate Identifier | The MessageID attribute of the inner XML message is not unique, and has already been used for a message with different content. This message has been rejected. | +| Already Submitted | The MessageID attribute of the inner XML message is not unique, but since the message content is the same as that of a previously accepted message, this copy can be considered to be successfully submitted as well. | +| ISP duration rejected | The message specifies a ISP duration that is not the agreed-upon common value for the market in which it is used. | +| Time zone rejected | The message specifies a time zone that has a different UTC offset than is the agreed- upon common value for the market. | +| Invalid congestion point | Unknown congestion point or the recipient is not active at this congestion point. | +| Unknown reference | The message with the sequence where is referred to is unknown.
For the concerning reference field name can be filled in (for example FlexRequestSequence or PrognosisSequence). | +| Reference Period mismatch | The message(s) with the sequence where is referred to contains a different Period. | +| Reference message expired | The message that is referred to is expired. | +| Reference message revoked | The message that is referred to is revoked. | +| ISPs out of bounds | One or more ISPs are outside the tolerated boundaries: ISPs do not exist. | +| ISP conflict | One or more ISPs are defined more than once, possibly because of an incorrect duration. | +| Period out of bounds | Period of the message is inappropriate.
For example: a FlexRequest with a Period in the past or a settlement item in a FlexSettlement with a Period outside the concerning settlement period. | +| ExpirationDateTime out of bounds | ExpirationDateTime is in the past or exceeds the ISPs in the message. | diff --git a/docs/use-case-descriptions/privacy-and-security-by-design.md b/specifications/3.0.0/docs/use-case-descriptions/privacy-and-security-by-design.md similarity index 100% rename from docs/use-case-descriptions/privacy-and-security-by-design.md rename to specifications/3.0.0/docs/use-case-descriptions/privacy-and-security-by-design.md diff --git a/docs/use-case-descriptions/reading-guidelines.md b/specifications/3.0.0/docs/use-case-descriptions/reading-guidelines.md similarity index 100% rename from docs/use-case-descriptions/reading-guidelines.md rename to specifications/3.0.0/docs/use-case-descriptions/reading-guidelines.md diff --git a/docs/use-case-descriptions/scope.md b/specifications/3.0.0/docs/use-case-descriptions/scope.md similarity index 100% rename from docs/use-case-descriptions/scope.md rename to specifications/3.0.0/docs/use-case-descriptions/scope.md diff --git a/specifications/3.0.0/docs/use-case-descriptions/use-cases/contract-phase.md b/specifications/3.0.0/docs/use-case-descriptions/use-cases/contract-phase.md new file mode 100644 index 00000000..7ad0cf35 --- /dev/null +++ b/specifications/3.0.0/docs/use-case-descriptions/use-cases/contract-phase.md @@ -0,0 +1,145 @@ + + +# Contract phase + +In [Contract phase](../../general-description/contract-phase.md) the informative description of the contract phase processes has been given. +In this chapter use cases will be described as derived from the contract phase. + +The USEF MCM contract phase specifies the following use cases: + +_Use cases for the Contract phase._ + +| Name | Direction | Message types | +|-------------------------------------------------------------------------------|-----------|-------------------------------------------------| +| [Publish Congestion Points (Long-term)](#publish-congestion-points-long-term) | DSO → CRO | DSOPortfolioUpdate / DSOPortfolioUpdateResponse | +| [Publish Connections](#publish-connections) | AGR → CRO | AGRPortfolioUpdate / AGRPortfolioUpdateResponse | + +## Publish Congestion Points (Long-term) + +Once a flexibility market is functional for an area, the DSO has to update and publish a register of possible congestion points, including the connection identifiers of connected prosumers. +This register is maintained by the Common Reference Operator. +If operating in open mode, the CRO will accept updates from any USEF-compliant participants implementing the DSO role. +In closed mode, participants will need to be pre-configured in order for updates to be accepted. + +Once populated, the common reference will allow AGRs to determine whether there are prosumers in their portfolio that can offer flexibility, via their connections, to one or more congestion points. + +
+ ![Exchange of congestion points including connections by DSO](../../assets/images/use-case-3-1-exchange-of-congestions-points.svg){ width=1000px } +
Exchange of congestion points including connections by DSO
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Publish Congestion Points / DSO Portfolio
Goal in contextIn order to predict congestion and create a flex market: publish Congestion Points – including their associated Connections – to the Common Reference, so they become available to the AGRs.
PreconditionsCommon Reference is available to DSO and AGRs
Successful outcomeThe Common Reference is updated with the latest Congestion points and associated Connections (i.e. all connected Prosumers)
Failure outcomeRejectionReasonCause of rejection
<See Message validation>DSOPortfolioUpdate failed to pass validation by the CRO
UnauthorizedCRO is operating in closed mode and the DSO is not pre-registered as an authorized participant
Connection conflict: [<Connection EntityAdress>] at [<CongestionPoint EntityAddress>]A connection is transmitted before at another Congestion Point. Return EntityAddress of the concerning Connection and Congestion Point where it has been placed before.
Subordinate sequence numberThe message sequence is lower than that of a previously received DSOPortfolioUpdate
[User defined]Any other reasonable cause to reject the message
+ +### Related information + +It is the responsibility of the CRO to have policies regarding access, data retention, data security and conflict resolution compliant with the USEF privacy & security guidelines. +If the CRO detects strange behavior in the periods (e.g.an EndPeriod in the far past, an EndPeriod earlier than the StartPeriod or an EndPeriod of a congestion point earlier than the EndPeriod of a connection that it contains), it is up to the CRO to decide whether to reject the message, adjust the period or reply with a warning. + +A DSO can update its portfolio by retransmitting the DSOPortfolioUpdate. +It is essential to use a sequence number that is incremented each time a new revision is sent so the order of transmission can be traced. +To remove a congestion point, the DSO can transmit a new DSOPortfolioUpdate where the EndPeriod is the current time. +The congestion point is then immediately expired. +It is not necessary to add connections to this message since they will also expire. + +## Publish Connections + +Once a flexibility market is functional for an area, the AGR has to publish a list of the connection identifiers of the prosumers it has contracted. +This list is stored and, subject to access controls, made available to other market participants by the CRO. + +
+ ![Exchange of connections by AGR](../../assets/images/use-case-3-2-exchange-of-connections-by-agr.svg){ width=1000px } +
Exchange of connections by AGR
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Publish Congestion Points / DSO Portfolio
Goal in contextPublish all contracted Prosumer Connections in the Common Reference, in order to later discover Congestion Points and associated DSOs and to register the AGR’s presence at Connections to the associated DSOs.
PreconditionsCommon Reference is available to DSO and AGRs
Successful outcomeThe Common Reference is updated with the all Prosumers (listed by their Connection identifiers) represented by the AGR.
Failure outcomeRejectionReasonCause of rejection
<See Message validation>AGRPortfolioUpdate failed to pass validation by the CRO
UnauthorizedCRO is operating in closed mode and the AGR is not pre-registered as an authorized participant
Subordinate sequence numberThe message sequence is lower than that of a previously received DSOPortfolioUpdate
[User defined]Any other reasonable cause to reject the message
+ +### Related information + +It is possible to transmit connection points to the CRO that have not yet been declared by the DSO. + +An AGR can update its portfolio by retransmitting the AGRPortfolioUpdate. +It is essential to use a sequence number that is incremented each time a new revision is sent, so the order of transmission can be traced. diff --git a/docs/use-case-descriptions/use-cases/operate-phase.md b/specifications/3.0.0/docs/use-case-descriptions/use-cases/operate-phase.md similarity index 100% rename from docs/use-case-descriptions/use-cases/operate-phase.md rename to specifications/3.0.0/docs/use-case-descriptions/use-cases/operate-phase.md diff --git a/specifications/3.0.0/docs/use-case-descriptions/use-cases/plan-phase.md b/specifications/3.0.0/docs/use-case-descriptions/use-cases/plan-phase.md new file mode 100644 index 00000000..5d51d4c6 --- /dev/null +++ b/specifications/3.0.0/docs/use-case-descriptions/use-cases/plan-phase.md @@ -0,0 +1,184 @@ + + +# Plan phase + +In [Plan phase](../../general-description/plan-phase.md) the informative description of the plan phase processes are provided. +In this chapter, use cases will be described as derived from the plan phase. + +The USEF MCM plan phase specifies the following use cases: + +_Use cases for the Plan phase._ + +| Name | Direction | Message types | +|-------------------------------------------------------------------------------------|-----------|-------------------------------------------------------| +| [Retrieve Congestion Points](#retrieve-congestion-points) | AGR → CRO | AGRPortfolioQuery / AGRPortfolioQueryResponse | +| [Retrieve Active Aggregators](#retrieve-active-aggregators) | DSO → CRO | DSOPortfolioQuery / DSOPortfolioQueryResponse | +| [Exchange Flexibility Reservation Update](#exchange-flexibility-reservation-update) | AGR ← DSO | FlexReservationUpdate / FlexReservationUpdateResponse | + +The use cases are explained in the following sections. + +If operating in open mode, the CRO will accept updates from any USEF-compliant participants implementing the AGR role. +In closed mode, participants will need to be pre-configured in order for updates to be accepted. + +## Retrieve Congestion Points + +The common reference allows an AGR to determine whether there are any congestion points where prosumers in its portfolio +can offer flexibility. + +
+ ![Retrieval of Congestion Points corresponding to AGR's connections](../../assets/images/use-case-3-3-retrieval-of-congestion-points.svg){ width=1000px } +
Retrieval of Congestion Points corresponding to AGR's connections
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Publish Congestion Points / DSO Portfolio
Goal in contextRetrieve a list of all registered Connections represented by this AGR, grouped by Congestion Point, in order to enable flex trading with the responsible DSO.
PreconditionsThe AGR has registered the Connection identifiers for which it represents Prosumers in the Common Reference.
Successful outcomeThe AGR receives a list of Connections, grouped by Connection Point and responsible DSO, and a list of Connections that have not been allocated to a DSO.
Failure outcomeRejectionReasonCause of rejection
<See Message validation>AGRPortfolioQuery failed to pass validation by the CRO
UnauthorizedCRO is operating in closed mode and the AGR is not pre-registered as an authorized participant
No connections availableThe AGR has no registered connections at the Common Reference
[User defined]Any other reasonable cause to reject the message
+ +### Related information + +AGRs will only obtain DSO identities, congestion point identifiers and connection identifiers for those connections they have registered in the common reference themselves. + +Registered connections that have not (yet) been allocated by a DSO are returned in a separate list, to inform the AGR that there is no DSO available to trade with at those connections. + +## Retrieve Active Aggregators + +If operating in open mode, the CRO will accept queries from any USEF-compliant participants implementing the AGR role. +In closed mode, participants will need to be pre-configured in order for updates to be accepted. + +
+ ![Retrieval of registered Connections, grouped by Congestion Point, including corresponding AGR identity](../../assets/images/use-case-3-4-retrieval-of-registered-connections.svg){ width=1000px } +
Retrieval of registered Connections, grouped by Congestion Point, including corresponding AGR identity
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Publish Congestion Points / DSO Portfolio
Goal in contextRetrieve a list of all DSO-registered Congestion Points with, for each such point, a list of AGRs representing Prosumers there, including the number of Connections each AGR represents.

The DSO then knows from which AGRs D-prognoses can be expected, and which percentage of the total Connections on each Congestion Point is affected by those prognoses.
PreconditionsThe DSO has determined its Congestion Points and published this information, including the associated Connection identifiers in the Common Reference.
The AGR has registered the Connection identifiers for which it represents Prosumers in the Common Reference (see UC1027)
Successful outcomeAGRs which represent Prosumers at any of the Congestion Points registered by the DSO are available to the DSO
Failure outcomeRejectionReasonCause of rejection
<See Message validation>DSOPortfolioQuery failed to pass validation by the CRO
UnauthorizedCRO is operating in closed mode and the AGR is not pre-registered as an authorized participant
No connections availableThe DSO has no registered connections at the Common Reference
[User defined]Any other reasonable cause to reject the message
+ +### Related information + +DSOs may only obtain AGR identities and combined connection counts for those congestion points they have registered in the common reference themselves. + +## Exchange Flexibility Reservation Update + +Where bilateral contracts are used, the FlexReservationUpdate message can be used at this stage to set or release reserved flexibility. + +
+ ![Exchange of FlexReservationUpdate](../../assets/images/use-case-3-5-exchange-of-flexreservationupdate.svg){ width=1000px } +
Exchange of FlexReservationUpdate
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Publish Congestion Points / DSO Portfolio
Goal in contextFor all reserved power in a bilateral contract, the DSO signals which part of the contracted volume is still reserved and which part is not needed and may be used for other purposes.
PreconditionsThe DSO and AGR have agreed on a bilateral contract (out of scope for UFTP) which the FlexReservationUpdate refers to.
Successful outcomeThe AGR has received the update and can potentially reoptimize its portfolio based on the changes. The DSO registers the update for settlement purposes.
Failure outcomeRejectionReasonCause of rejection
<See Message validation>FlexReservationUpdate failed to pass validation by the AGR
Deadline expiredThe deadline for the DSO to release reserved flexibility has expired
Power value rejectionOne or more Power values in the FlexReservationUpdate are not conform agreement
[User defined]Any other reasonable cause to reject the message
diff --git a/specifications/3.0.0/docs/use-case-descriptions/use-cases/settle-phase.md b/specifications/3.0.0/docs/use-case-descriptions/use-cases/settle-phase.md new file mode 100644 index 00000000..bcd470d2 --- /dev/null +++ b/specifications/3.0.0/docs/use-case-descriptions/use-cases/settle-phase.md @@ -0,0 +1,77 @@ + + +# Settle phase + +The informative description of the settle phase processes are provided in [Settle phase](../../general-description/settle-phase.md). +In this chapter, the use cases will be described, as derived from the settle phase. + +The USEF MCM settle phase specifies the following use case: + +_Use cases for the settle phase._ + +| Name | Direction | Message types | +|-------------------------------------------------------|-----------|----------------------------------------| +| [Process Settlement Items](#process-settlement-items) | AGR ← DSO | FlexSettlement/ FlexSettlementResponse | + +## Process Settlement Items + +
+ ![Transmission of settlement including acceptance process per settlement item](../../assets/images/use-case-3-11-transmission-of-settlement.svg){ width=1000px } +
Transmission of settlement including acceptance process per settlement item
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Revoke FlexOrder
Goal in contextDSO sends consolidated settlement volumes and prices to the AGR for a specific period. AGR verifies the settlement calculations performed by DSO: acknowledge settlement items that are plausible according to the AGR or start a dispute process if they show disputable results. AGR returns the list of verified settlement items.
PreconditionsAll settlement items within the period are available and complete
Successful outcomePeriodic settlement invoice sent by DSO, validated by AGR and a potential dispute process is started.
Failure outcomeRejectionReasonCause of rejection
<See Message validation>FlexSettlement failed to pass validation by the AGR
Missing Settlement ItemsNot all flexibility that have been procured within the given period is included as a settlement item.
PeriodStart rejectedThe settlement period starts too late (for example in case there are unsettled items from an earlier period) or is not plausible (for example in case it starts in the future).
PeriodEnd rejectedThe settlement period ends too early (for example in case there are unsettled items from a later period that have to be treated too) or is not plausible (for example in case it is earlier than the PeriodStart or in the future).
[User defined]Any other reasonable cause to reject the message
+ +### Related information + +If settlement items are missing, the message should be rejected (as mentioned in failure outcome). +This is to encourage sending of all required information necessary to settle trades as soon as possible, thereby avoiding a series of unsettled trades for a given period. + +Note that the rejection of a FlexSettlement message is not a means of raising a dispute for settlement items. +The dispute process is out-of-scope for USEF. diff --git a/specifications/3.0.0/docs/use-case-descriptions/use-cases/validate-phase.md b/specifications/3.0.0/docs/use-case-descriptions/use-cases/validate-phase.md new file mode 100644 index 00000000..d04d9b75 --- /dev/null +++ b/specifications/3.0.0/docs/use-case-descriptions/use-cases/validate-phase.md @@ -0,0 +1,314 @@ + + +# Validate phase + +In [Validate phase](../../general-description/validate-phase.md), informative description of the validate phase processes has been given. In this chapter the use cases will be described as derived from the validate phase. + +The USEF MCM validate phase specifies the following use cases: + +_Use cases for the Validate phase._ + +| Name | Direction | Message types | +|-----------------------------------------------------------------------------------------|-----------|---------------------------------------------------| +| [Exchange D-Prognoses per Congestion Point](#exchange-d-prognoses-per-congestion-point) | AGR → DSO | Prognosis / PrognosisResponse | +| [Exchange Flexibility Requests](#exchange-flexibility-requests) | AGR ← DSO | FlexRequest / FlexRequestResponse | +| [Exchange Flexibility Offers](#exchange-flexibility-offers) | AGR → DSO | FlexOffer / FlexOfferResponse | +| [Revocation Flexibility Offer](#revocation-flexibility-offer) | AGR → DSO | FlexOfferRevocation / FlexOfferRevocationResponse | +| [Exchange Flexibility Orders](#exchange-flexibility-orders) | AGR ← DSO | FlexOrder / FlexOrderResponse | + +The use cases are explained in the following sections. + +## Exchange D-Prognoses per Congestion Point + +
+ ![Exchange of D-prognoses](../../assets/images/use-case-3-6-exchange-of-d-prognoses.svg){ width=1000px } +
Exchange of D-prognoses
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
D-prognosis
Goal in contextD-prognoses are (re)created by the AGR per congestion point, based on its portfolio. These D-prognoses will be submitted to the DSO. D-prognoses should be submitted at least once before the gate closure time. D-prognoses can be updated by transmitting a new one.
PreconditionsCongestion point(s) defined and retrieved from the CRO, AGR per congestion point retrieved from CRO by DSO, AGR-DSO contracts in place.
Successful outcomeD-prognosis message created and accepted by the DSO for each congestion point on which the AGR has active Connections
Failure outcomeRejectionReasonCause of rejection
<See Message validation>D-prognosis failed to pass validation by the DSO
Lacking ISPsThe prognosis does not include all ISPs in the Period it applies to
Power value rejectionOne or more Power values in the prognosis are not plausible
Subordinate sequence numberThe message sequence is lower than that of a previously received D-prognosis
[User defined]Any other reasonable cause to reject the message
+ +### Related information + +Congestion points (with associated DSOs) at which the AGR has contracted prosumers, and active AGRs, are available via the common reference and should have been retrieved prior to executing this use case. + +It is essential to use a sequence number that is incremented each time a new revision is sent so the order of transmission can be traced. + +## Exchange Flexibility Requests + +
+ ![Exchange of FlexRequests](../../assets/images/use-case-3-7-exchange-of-flexrequests.svg){ width=1000px } +
Exchange of FlexRequests
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlexRequest
Goal in contextIf grid congestion is expected, requests for flexibility are created by the DSO and sent to AGRs potentially capable of helping to reduce that congestion. These requests serve as the basis for subsequent flexibility offers.
PreconditionsAGR-DSO market contract in place.
One or more Congestion Points registered in the Common Reference, with at least one AGR with contracted Connections on that point.
DSO grid safety analysis performed.
Successful outcomeFlexibility requests submitted to AGR(s)
Failure outcomeRejectionReasonCause of rejection
<See Message validation>FlexRequest failed to pass validation by the AGR
Lacking Requested DispositionThe FlexRequest has no ISP with a “requested” disposition.
Requested Power discrepancyOne or more ISPs with a "requested" disposition has no direction: MinPower < 0 and MaxPower > 0.
Power discrepancyOne or more ISPs has a higher MinPower than MaxPower value.
[User defined]Any other reasonable cause to reject the message
+ +### Related information + +Each flexibility request should include the ISPs for which congestion is expected, including a direction (MinPower ≥ 0 or MaxPower ≤ 0), and it is advisable to send multiple ISPs for which capacity is still available, to allow AGRs to time-shift load. +For each period during which congestion is expected, the DSO may create any number of flexibility requests (including no requests at all). +If multiple requests are created, their content must not be identical. +Which variations (more/less requested power per ISP, time-shift of load) are created is a DSO-internal business decision. + +## Exchange Flexibility Offers + +
+ ![Exchange of FlexOffers](../../assets/images/use-case-3-8-exchange-of-flexoffers.svg){ width=1000px } +
Exchange of FlexOffers
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlexOffer
Goal in contextThe AGR creates flexibility offers based on previous DSO flexibility requests and sends these to the originating DSOs. It is also possible to send FlexOffers that do not originate from a FlexRequest, which are called unsolicited FlexOffers. Each offer indicates to which extent the AGR can provide flexibility, what the effect on its baseline will be and what the price for the flexibility would be.
PreconditionsAGR-DSO market contract in place.
AGR has at least one contracted Connection on the Congestion point. Flexibility offers can be based on previous flexibility requests that have been accepted and stored, or be initiated without a preliminary flex request (called an unsolicited flex offer).
Successful outcomeFlexibility offers sent to the DSO
Failure outcomeRejectionReasonCause of rejection
<See Message validation>FlexOffer failed to pass validation by the DSO
No baselineThe AGR has no valid baseline, possibly lacking a valid D-prognosis
Power value rejectionOne or more Power values in the FlexOffer are not plausible
Request mismatchNone of the ISPs with a "requested" disposition in the referred FlexRequest, is mentioned in the FlexOffer
No MutEx offer supportThe FlexOffer contains mutual exclusive offers (OfferOptions), which is not supported by the DSO
[User defined]Any other reasonable cause to reject the message
+ +### Related information + +- USEF does not specify how the AGR determines the optimal flexibility offer, offer price or optimal timing to send the offer to the DSO. +- AGRs may choose to send multiple FlexOffer messages: this includes sending a FlexOffer that better meets the DSO request at a much later time when circumstances have changed. +Unsolicited FlexOffers are also allowed, in which case the FlexRequestOrigin and FlexRequestSequence fields are empty. +- Sending a FlexOffer for partial activation is always allowed, although it is ignored by the DSO if it does not support partial activation (in which case the MinActivationFactor is always 1). + +Note that acceptance of the FlexOffer message does not imply ordering of the flexibility. + +## Revocation Flexibility Offer + +
+ ![Revocation of FlexOffer](../../assets/images/use-case-3-9-revocation-of-flexoffer.svg){ width=1000px } +
Revocation of FlexOffer
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Revoke FlexOffer
Goal in contextWhen a previously sent flexibility offer is no longer valid, despite the validity period of the offer not having expired yet, the AGR informs the DSO that the offer is revoked. After revocation, the DSO cannot order the flexibility from this offer anymore.
PreconditionsThe concerning flexibility offer has been sent to and acknowledged by the DSO, and has not (yet) been procured using a FlexOrder
Successful outcomeFlexibility offer revocation notification submitted to the DSO
Failure outcomeRejectionReasonCause of rejection
<See Message validation>FlexOfferRevocation failed to pass validation by the DSO
Flexibility procuredThe FlexOffer cannot be revoked because its flexibility has already been ordered
[User defined]Any other reasonable cause to reject the message
+ +### Related information + +Only flexibility offers communicated using a FlexOffer message which has already been acknowledged by the DSO can be revoked. +If the acknowledgement is still pending, the AGR should delay sending its FlexOfferRevocation message until the acknowledgement has been received. +When the DSO receives a revocation of a flexibility offer it wants to order, this is not a valid base to reject the revocation. +After revocation, the offer can no longer be ordered. + +FlexOffers may be revoked at any time in the plan and validate phases (and also in operate phase as described in [Revocation Flexibility Offer](operate-phase.md#revocation-flexibility-offer)), unless there is already a FlexOrder based on the offer. +Notice that FlexOrders and FlexOfferRevocations can cross each other. +Where this is the case, priority should be given to the FlexOfferRevocation. + +## Exchange Flexibility Orders + +
+ ![Exchange of FlexOrder](../../assets/images/use-case-3-10-exchange-of-flexoffer.svg){ width=1000px } +
Exchange of FlexOrder
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlexOrder
Goal in contextProcess for the DSO to accept (some) flexibility offers to solve Congestion based on the Prognosis.
PreconditionsCorresponding FlexOffer has been received and accepted by DSO and is still valid.
Successful outcomeFlexibility procured
Failure outcomeRejectionReasonCause of rejection
<See Message validation>FlexOrder failed to pass validation by the AGR
ISP mismatchISPs from the FlexOrder do not match the ISPs given in the FlexOffer
Power mismatchOrdered flexibility does not match the offered flexibility
Price mismatchPrice in the order does not match the price given in the offer
[User defined]Any other reasonable cause to reject the message
+ +### Related information + +The DSO needs to make its own decisions about which FlexOffers to accept. +FlexOffers can only be ordered once and have to be ordered as specified in the corresponding offer for the specified price. +Only in situations where partial activation is supported and offered in the FlexOffer can the ISP power and price be altered to conform to the specifications from Section [Flexibility trading between the AGR and DSO](../../general-description/validate-phase.md#flexibility-trading-between-the-agr-and-dso). +After a successful FlexOrder transmission, the AGR is responsible for providing the ordered flexibility via an updated D-prognosis which reflects the traded flexibility. diff --git a/specifications/3.0.0/docs/versions.md b/specifications/3.0.0/docs/versions.md new file mode 100644 index 00000000..299e2c9a --- /dev/null +++ b/specifications/3.0.0/docs/versions.md @@ -0,0 +1,19 @@ + + +# Versioned specification files + +The XSD links below point to immutable version snapshots in the repository. The v3 PDF and Word files are the original artifacts from their respective release tags. + +| Version | Markdown and images | XSD files | PDF | Word | +| --- | --- | --- | --- | --- | +| 1.0.1 | Not archived | [Browse XSDs](https://github.com/shapeshifter/shapeshifter-specification/tree/main/specifications/1.0.1/xsd) | Not archived | Not archived | +| 2.0.0 | Not archived | [Browse XSDs](https://github.com/shapeshifter/shapeshifter-specification/tree/main/specifications/2.0.0/xsd) | Not archived | Not archived | +| 3.0.0 | [Browse docs](https://github.com/shapeshifter/shapeshifter-specification/tree/main/specifications/3.0.0/docs) | [Browse XSDs](https://github.com/shapeshifter/shapeshifter-specification/tree/main/specifications/3.0.0/xsd) | [Download PDF](https://github.com/shapeshifter/shapeshifter-specification/blob/main/specifications/3.0.0/USEF%20Flex%20Trading%20Protocol%20Specifications%203.0.0.pdf?raw=1) | [Download Word](https://github.com/shapeshifter/shapeshifter-specification/blob/main/specifications/3.0.0/USEF%20Flex%20Trading%20Protocol%20Specifications%203.0.0.docx?raw=1) | +| 3.1.0 | [Browse docs](https://github.com/shapeshifter/shapeshifter-specification/tree/main/specifications/3.1.0/docs) | [Browse XSDs](https://github.com/shapeshifter/shapeshifter-specification/tree/main/specifications/3.1.0/xsd) | [Download PDF](https://github.com/shapeshifter/shapeshifter-specification/blob/main/specifications/3.1.0/USEF%20Flex%20Trading%20Protocol%20Specifications%203.1.0.pdf?raw=1) | [Download Word](https://github.com/shapeshifter/shapeshifter-specification/blob/main/specifications/3.1.0/USEF%20Flex%20Trading%20Protocol%20Specifications.docx?raw=1) | +| Development | [Browse docs](https://github.com/shapeshifter/shapeshifter-specification/tree/main/specifications/development/docs) | [Browse XSDs](https://github.com/shapeshifter/shapeshifter-specification/tree/main/specifications/development/xsd) | Not published | Not published | + +The header version selector links to the published documentation versions. The current draft is published at `/development/` and is not a numbered release. \ No newline at end of file diff --git a/specifications/3.0.0/xsd/UFTP-agr-cro.xsd b/specifications/3.0.0/xsd/UFTP-agr-cro.xsd new file mode 100644 index 00000000..0544ac8a --- /dev/null +++ b/specifications/3.0.0/xsd/UFTP-agr-cro.xsd @@ -0,0 +1,167 @@ + + + + + + + + + + + + + + + Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. + + + + + + + + + + + A connection that the AGR want the CRO to update + + + + EntityAddress of the Connection entity being updated. + + + + + The first Period hat the AGR represents the prosumer at this Connection. + + + + + The last Period that the AGR represents the prosumer at this Connection, if applicable. + + + + + + + + + + + + MessageID of the AGRPortfolioUpdate that has just been accepted or rejected + + + + + + + + + + + + + + Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. + + + + + The Period for which the AGR requests the portfolio information. + + + + + + + + + + + + + + + + + Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. + + + + + MessageID of the AGRPortfolioQuery that has just been accepted or rejected + + + + + The Period that the portfolio is valid. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + EntityAddress of the CongestionPoint. + + + + + Indicates whether the DSO accepts mutual exclusive FlexOffers on this CongestionPoint. + + + + + Indicates which party is responsible for day-ahead redispatch. + + + + + Indicates which party is responsible for intraday ahead redispatch, AGR or DSO. If not specified, there will be no intraday trading on this CongestionPoint. + + + + + + + + + + EntityAddress of the Connection. + + + + + + + + + + + diff --git a/specifications/3.0.0/xsd/UFTP-agr-dso.xsd b/specifications/3.0.0/xsd/UFTP-agr-dso.xsd new file mode 100644 index 00000000..a67615c2 --- /dev/null +++ b/specifications/3.0.0/xsd/UFTP-agr-dso.xsd @@ -0,0 +1,690 @@ + + + + + + + + + + + + + + ISO 8601 time interval (minutes only, for example PT15M) indicating the duration of the ISPs referenced in this message. Although the ISP length is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant ISP duration. + + + + + Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. + + + + + Day (in yyyy-mm-dd format) the ISPs referenced in this Flex* message belong to. + + + + + Entity Address of the Congestion Point this D-Prognosis applies to. + + + + + + + + + + + + + + The ISP represents one or more Imbalance Settlement Periods and is used by Prognosis and Flex-related messages. + + + + + + Revision of this message. A sequence number that must be incremented each time a new revision of a + prognosis is sent. The combination of SenderDomain and PrognosisSequence should be unique + + + + + + + + + + + + Power specified for this ISP in Watts. Also see the important notes about the sign of this attribute in the main documentation entry for the ISP element. + + + + + Number of the first ISPs this element refers to. The first ISP of a day has number 1. + + + + + The number of the ISPs this element represents. Optional, default value is 1. + + + + + + + + + + + + + + + + + + + + + + MessageID of the D-Prognosis message this request is based on. + + + + + + + + + + + + + + The ISP represents one or more Imbalance Settlement Periods and is used by Prognosis and Flex-related messages. + + + + + + Reference to the bilateral contract in question. + + + + + Message reference, assigned by the DSO originating the FlexReservationUpdate. + + + + + + + + + + + + Remaining reserved power specified for this ISP in Watts. + + + + + Number of the first ISPs this element refers to. The first ISP of a day has number 1. + + + + + The number of the ISPs this element represents. Optional, default value is 1. + + + + + + + + + + + + MessageID of the FlexReservationUpdate message this request is based on. + + + + + + + + + + + + + + The ISP represents one or more Imbalance Settlement Periods and is used by Prognosis and Flex-related messages. + + + + + + Revision of this message, a sequence number that must be incremented each time a new revision of a + FlexRequest message is sent. + + + + + Date and time, including the time zone (ISO 8601 formatted as per http://www.w3.org/TR/NOTE-datetime) until which the FlexRequest message is valid. + + + + + Reference to the concerning contract, if applicable. The contract may be either bilateral or commoditized market contract. Each contract may specify multiple service-types. + + + + + Service type for this request, the service type determines response characteristics such as latency or asset participation type. + + + + + + + + + + + + + Power specified for this ISP in Watts. Also see the important notes about the sign of this attribute in the main documentation entry for the ISP element. + + + + + Power specified for this ISP in Watts. Also see the important notes about the sign of this attribute in the main documentation entry for the ISP element. + + + + + Number of the first ISPs this element refers to. The first ISP of a day has number 1. + + + + + The number of the ISPs this element represents. Optional, default value is 1. + + + + + + + + + + + + MessageID of the FlexRequest message this request is based on. + + + + + + + + + + + + + + If the DSO does not support mutually exclusive offers it will reject FlexOffers that contain more than one OfferOption. + + + + + + Date and time, including the time zone (ISO 8601 formatted as per http://www.w3.org/TR/NOTE-datetime) until which the FlexOffer is valid. + + + + + MessageID of the FlexRequest message this request is based on. Mandatory if and only if solicited. + + + + + Reference to the concerning contract, if applicable. The contract may be either bilateral or commoditized market contract. + + + + + MessageID of the D-Prognosis this request is based on, if it has been agreed that the baseline is based on D-prognoses. + + + + + Identification of the baseline prognosis, if another baseline methodology is used than based on D-prognoses + + + + + ISO 4217 code indicating the currency that applies to the price of the FlexOffer. + + + + + + + + + + + + The ISP represents one or more Imbalance Settlement Periods and is used by Prognosis and Flex-related messages. + + + + + + The identification of this option. + + + + + The asking price for the flexibility offered in this option. + + + + + The minimal activation factor for this OfferOption. An AGR may choose to include MinActivationFactor in FlexOffers even if the DSO is not interested in partial activation. In that case the DSO will simply use an ActivationFactor of 1.00 in every FlexOrder. + + + + + + + + + + Power specified for this ISP in Watts. Also see the important notes about the sign of this attribute in the main documentation entry for the ISP element. + + + + + Number of the first ISPs this element refers to. The first ISP of a day has number 1. + + + + + The number of the ISPs this element represents. Optional, default value is 1. + + + + + + + + + + MessageID of the FlexOffer message this request is based on. + + + + + + + + + + + + MessageID of the FlexOffer message that is being revoked: this FlexOffer must have been accepted previously. + + + + + + + + + + + + MessageID of the FlexOfferRevocation message this request is based on. + + + + + + + + + + + + The ISP represents one or more Imbalance Settlement Periods and is used by Prognosis and Flex-related messages. + + + + + + MessageID of the FlexOffer message this order is based on. + + + + + Reference to the concerning bilateral contract, if applicable. + + + + + MessageID of the D-Prognosis this request is based on, if it has been agreed that the baseline is based on D-prognoses. + + + + + Identification of the baseline prognosis, if another baseline methodology is used than based on D-prognoses + + + + + The price for the flexibility ordered. Usually, the price should match the price of the related FlexOffer. + + + + + ISO 4217 code indicating the currency that applies to the price of the FlexOffer. + + + + + Order number assigned by the DSO originating the FlexOrder. To be stored by the AGR and used in the settlement phase. + + + + + The OptionReference from the OfferOption chosen from the FlexOffer. + + + + + The activation factor for this OfferOption. The ActivationFactor must be greater than or equal to the MinActivationFactor in the OfferOption chosen from the FlexOffer. + + + + + + + + + + Power specified for this ISP in Watts. Also see the important notes about the sign of this attribute in the main documentation entry for the ISP element. + + + + + Number of the first ISPs this element refers to. The first ISP of a day has number 1. + + + + + The number of the ISPs this element represents. Optional, default value is 1. + + + + + + + + + + MessageID of the FlexOrder that has just been accepted or rejected. + + + + + + + + + + + + + + + + First Period of the settlement period this message applies to. + + + + + Last Period of the settlement period this message applies to. + + + + + ISO 4217 code indicating the currency that applies to all amounts (flex price, penalty and net settlement) in this message. + + + + + + + + + + + + + Order reference assigned by the DSO when originating the FlexOrder. + + + + + + + + + + Reference to the concerning bilateral contract, if it is linked to it + + + + + MessageID of the Prognosis message (more specifically: the D-Prognosis) the FlexOrder is based on, if it has been agreed that the baseline is based on D-prognoses. + + + + + Identification of the baseline prognosis, if another baseline methodology is used than based on D-prognoses. + + + + + Entity Address of the Congestion Point the FlexOrder applies to. + + + + + The price accepted for supplying the ordered amount of flexibility as per the referenced FlexOrder messages. + + + + + Penalty due a non-zero PowerDeficiency + + + + + Net settlement amount for this Period: Price minus Penalty. + + + + + + + + Number of the first ISPs this element refers to. The first ISP of a day has number 1. + + + + + The number of the ISPs this element represents. Optional, default value is 1. + + + + + Power originally forecast (as per the referenced baseline) for this ISP in Watts. + + + + + Amount of flex power ordered (as per the referenced FlexOrder message) for this ISP in Watts. + + + + + Actual amount of power for this ISP in Watts, as measured/determined by the DSO and allocated to the AGR. + + + + + + Actual amount of flex power delivered for this ISP in Watts, as determined by the DSO. + + + + + Amount of flex power sold but not delivered for this ISP in Watts, as determined by the DSO. + + + + + + + + + + The ISP represents one or more Imbalance Settlement Periods and is used by Prognosis and Flex-related messages. + + + + + + MessageID of the FlexSettlement message that has just been accepted or rejected + + + + + + + + + + Order reference assigned by the DSO when originating the FlexOrder. + + + + + Indication whether the AGR accepts the order settlement details provided by the DSO (and will invoice accordingly), or disputes these details. + + + + + In case the order settlement was disputed, this attribute must contain a human-readable description of the reason. + + + + + + + + + + + + + + Reference to the concerning bilateral contract. + + + + + + + + + + + Period the being settled. + + + + + + + + Number of the first ISPs this element refers to. The first ISP of a day has number 1. + + + + + The number of the ISPs this element represents. Optional, default value is 1. + + + + + Amount of flex power that has been reserved (and not released using a FlexReservationUpdate message). + + + + + Amount of flex power that has been both reserved in advance and has been requested using a + FlexRequest (i.e. the lowest amount of flex power for this ISP). If there was no FlexRequest, + this field is omitted. + + + + + Amount of flex power that is considered available based on the FlexRequest in question. In case RequestedPower=0, AvailablePower is defined so that the offered power is allowed to be between 0 and AvailablePower in terms of compliancy (see Appendix 3 for details). In case RequestedPower ≠0, AvailablePower is defined so that the offered power is allowed to exceed the amount of requested power up to AvailablePower. If this is relevant for settlement, the DSO can include this field. + + + + + Amount of flex power that has been reserved in advance, requested using a FlexRequest and covered in an offer from the AGR. If there was no offer, this field is omitted. If there were multiple offers, only the one is considered that is most compliant . + + + + + Amount of flex power that has been ordered using a FlexOrder message that was based on a FlexOffer, both linked to this contract. If there was no order, this field is omitted. + + + + + + + + + + + + + + + + + + + diff --git a/specifications/3.0.0/xsd/UFTP-agr.xsd b/specifications/3.0.0/xsd/UFTP-agr.xsd new file mode 100644 index 00000000..0c1c9202 --- /dev/null +++ b/specifications/3.0.0/xsd/UFTP-agr.xsd @@ -0,0 +1,6 @@ + + + + + + diff --git a/specifications/3.0.0/xsd/UFTP-common.xsd b/specifications/3.0.0/xsd/UFTP-common.xsd new file mode 100644 index 00000000..69dd8dcd --- /dev/null +++ b/specifications/3.0.0/xsd/UFTP-common.xsd @@ -0,0 +1,229 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The SignedMessage element represents the secure wrapper used to submit USEF XML messages from the local message queue to the message queue of a remote participant. It contains minimal metadata (which is distinct from the common metadata used for all other messages), allowing the recipient to look up the sender's cryptographic scheme and public keys, and the actual XML message, as transformed (signed/sealed) using that cryptographic scheme. + + + + The Internet domain of the USEF participant sending this message. Upon receiving a message, the recipient should validate that its value matches the corresponding attribute value specified in the inner XML message, once un-sealed: if not, the message must be rejected as invalid. + + + + + The USEF role of the participant sending this message: AGR, BRP, CRO, DSO or MDC. Receive-time validation should take place as described for the SenderDomain attribute above. + + + + + The Base-64 encoded inner XML message contained in this wrapper, as transformed (signed/sealed) using the sender's cryptographic scheme. The recipient can determine which scheme applies using a DNS or configuration file lookup, based on the combination of SenderDomain and SenderRole. + + + + + + + + + + Version of the Shapeshifter specification used by the USEF participant sending this message. + + + + + The Internet domain of the USEF participant sending this message. When receiving a message, its value should match the value specified in the SignedMessage wrapper: otherwise, the message must be rejected as invalid. When replying to this message, this attribute is used to look up the USEF endpoint the reply message should be delivered to. + + + + + Internet domain of the participant this message is intended for. When sending a message, this attribute, combined with the RecipientRole, is used to look up the USEF endpoint the message should be delivered to. + + + + + Date and time this message was created, including the time zone (ISO 8601 formatted as per http://www.w3.org/TR/NOTE-datetime). + + + + + Unique identifier (UUID/GUID as per IETF RFC 4122) for this message, to be generated when composing each message. + + + + + Unique identifier (UUID/GUID as per IETF RFC 4122) used to correlate responses with requests, to be generated when composing the first message in a conversation and subsequently copied from the original message to each reply message. + + + + + + + + + + + + Indication whether the query was executed successfully or failed. + + + + + In case the query failed, this attribute must contain a human-readable description of the failure reason. + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/specifications/3.0.0/xsd/UFTP-cro-dso.xsd b/specifications/3.0.0/xsd/UFTP-cro-dso.xsd new file mode 100644 index 00000000..163fc510 --- /dev/null +++ b/specifications/3.0.0/xsd/UFTP-cro-dso.xsd @@ -0,0 +1,188 @@ + + + + + + + + + + + + + + + Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. + + + + + + + + + + + A congestion point that the DSO wants the CRO to update + + + + + + + EntityAddress of the Connection. + + + + + The first Period that the Connection is part of this CongestionPoint. + + + + + The last Period that the Connection is part of this CongestionPoint. + + + + + Indicates whether the DSO accepts mutual exclusive FlexOffers on this CongestionPoint. + + + + + Indicates which party is responsible for day-ahead redispatch. + + + + + Indicates which party is responsible for intraday ahead redispatch, AGR or DSO. If not specified, there will be no intraday trading on this CongestionPoint. + + + + + + + + + A connection that the DSO wants the CRO to update + + + + EntityAddress of the Connection. + + + + + The first Period that the Connection is part of this CongestionPoint. + + + + + The last Period that the Connection is part of this CongestionPoint. + + + + + + + + + + + + MessageID of the DSOPortfolioUpdateResponse that has just been accepted or rejected + + + + + + + + + + + + + + Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. + + + + + The Period for which the AGR requests the portfolio information. + + + + + EntityAddress of the CongestionPoint + + + + + + + + + + + + + + + + + MessageID of the AGRPortfolioQuery that has just been accepted or rejected + + + + + Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. + + + + + The Period for which the AGR requests the portfolio information. + + + + + + + + + + + + + + + EntityAddress of the Connection. + + + + + + + + + A Connection that is part of the congestion point. + + + + EntityAddress of the Connection. + + + + + The internet domain of the AGR that represents the prosumer connected on this Connection, if applicable. + + + + + + + + + + + diff --git a/specifications/3.0.0/xsd/UFTP-cro.xsd b/specifications/3.0.0/xsd/UFTP-cro.xsd new file mode 100644 index 00000000..6b706609 --- /dev/null +++ b/specifications/3.0.0/xsd/UFTP-cro.xsd @@ -0,0 +1,6 @@ + + + + + + diff --git a/specifications/3.0.0/xsd/UFTP-dso.xsd b/specifications/3.0.0/xsd/UFTP-dso.xsd new file mode 100644 index 00000000..3a86685f --- /dev/null +++ b/specifications/3.0.0/xsd/UFTP-dso.xsd @@ -0,0 +1,6 @@ + + + + + + diff --git a/specifications/3.0.0/xsd/UFTP-metering.xsd b/specifications/3.0.0/xsd/UFTP-metering.xsd new file mode 100644 index 00000000..3ba52e59 --- /dev/null +++ b/specifications/3.0.0/xsd/UFTP-metering.xsd @@ -0,0 +1,157 @@ + + + + + + + + + + + + + + + + + + + + + + kW must be used with Power profile values. + + + + + kWh must be used with energy profile values (ImportEnergy,ExportEnergy,ImportMeterReading,ExportMeterReading). + + + + + + + + + + + + The average active power during ISP, considering both import and export energy. Power=(ImportEnergy-ExportEnergy)*(60/ISP-Length-Minutes). + For example with a 15 minute ISP length we have a multiplier of 4, with a 30 minute ISP length we have a multiplier of 2. + Including the power profile is recommended. It is expected that in the following major version the power will become a mandatory value. + + + + + + Imported active energy, consumed during the ISP + + + + + Exported active energy, generated during the ISP + + + + + Cumulative metered imported active energy reading, at the end of the ISP + + + + + Cumulative metered exported active energy reading, at the end of the ISP + + + + + + + + + + + + + The message must contain one or more profiles with metering, energy or price values. + + + + + + Revision of this message. A sequence number that must be incremented each time a new revision of a metering message is sent. + + + + + ISO 8601 time interval (minutes only, for example PT15M) indicating the duration of the ISPs referenced in this message. Although the ISP length is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant ISP duration. + + + + + Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. + + + + + ISO 4217 code indicating the currency that applies to the price of the Tariff Rates. Only required if ImportTariff or ExportTariff profiles are included. + + + + + Day (in yyyy-mm-dd format) the ISPs referenced in this Metering message belong to. + + + + + EAN of the meter the message applies to. + + + + + + + + + + + A profile carries a sequence of ISPs with a defined type of metering data + + + + + + + + + + + + + + Number of the ISP this element refers to. The first ISP of a day has number 1. + + + + + Metering, energy or price value at the end of this ISP, in the designated profile units. + + + + + + + + + + + + MessageID of the Metering message this response is based on. + + + + + + + + + \ No newline at end of file diff --git a/specifications/3.1.0/README.md b/specifications/3.1.0/README.md new file mode 100644 index 00000000..695ad507 --- /dev/null +++ b/specifications/3.1.0/README.md @@ -0,0 +1,11 @@ +# Shapeshifter Specification 3.1.0 + +This directory preserves the XSD snapshot defined by the `V3.1.0` Git tag. + +Source tag: [`V3.1.0`](https://github.com/shapeshifter/shapeshifter-specification/tree/V3.1.0) at commit `3078c25a067c641dacd38ae8bde1ba4b4fe48413`. + +The `docs/` Markdown and image snapshot is from [commit `92ef001`](https://github.com/shapeshifter/shapeshifter-specification/commit/92ef001b79c6312403e4e463bcbc827c14f5a389), the last documentation state before the `V3.1.0` release tag. The release tag's branch does not contain the Markdown conversion. + +`docs/versions.md` is a shared migration index added after the historical snapshot to support the version selector and artifact downloads. + +The original XSD filenames, schema references, Markdown paths, and image references are retained. Do not edit this snapshot; make specification changes in the development sources and publish them as a new version. \ No newline at end of file diff --git a/specifications/3.1.0/USEF Flex Trading Protocol Specifications 3.1.0.pdf b/specifications/3.1.0/USEF Flex Trading Protocol Specifications 3.1.0.pdf new file mode 100644 index 00000000..8c45c92c Binary files /dev/null and b/specifications/3.1.0/USEF Flex Trading Protocol Specifications 3.1.0.pdf differ diff --git a/specifications/3.1.0/USEF Flex Trading Protocol Specifications.docx b/specifications/3.1.0/USEF Flex Trading Protocol Specifications.docx new file mode 100644 index 00000000..07a3f826 Binary files /dev/null and b/specifications/3.1.0/USEF Flex Trading Protocol Specifications.docx differ diff --git a/specifications/3.1.0/docs/about/levels-of-compliancy.md b/specifications/3.1.0/docs/about/levels-of-compliancy.md new file mode 100644 index 00000000..0d3ca92f --- /dev/null +++ b/specifications/3.1.0/docs/about/levels-of-compliancy.md @@ -0,0 +1,42 @@ + + +# Levels of compliancy + +UFTP has mandatory components and optional components. +The tables below list all core and optional components. +Support of core components is mandatory for all implementations. +Optional components are signaled throughout the document. +Optional components in messages are always prefixed with [optional]. + + +| Core UFTP components | USEF 2015 | UFTP | Signaled in CRO? | +| ------------------------------------ | :-------: | :----: | :--------------: | +| **UFTP process:** | | | | +| Day-ahead Flex trading | o | o | - | +| Redispatch responsibility choice | - | o | Y | +| Baseline choice | - | o | Y | +| **Market messages:** | | | | +| FlexRequest | o | o | - | +| FlexOffer | o | o | - | +| FlexOfferRevocation | o | o | - | +| FlexOrder | o | o | - | +| FlexSettlement | o | o | - | + +| Optional UFTP components | USEF 2015 | UFTP | Signaled in CRO? | +|--------------------------------------|:---------:|:------:|:----------------:| +| **UFTP Process:** | | | | +| Intraday Flex Trading | o | o | N | +| Availability contracts (FlexOptions) | ~[^1] | o | N | +| Dynamic pooling | - | future | ? | +| **Market messages:** | | | | +| D-prognosis | o | o | Y | +| FlexReservationUpdate | - | o | N | +| FlexOffer: mutual exclusive offers | - | o | Y | +| FlexOffer: unsolicited offers | - | o | - | +| FlexOffer: partial activation | - | o | - | + +[^1]: Availability contracts were mentioned in USEF2015, but not all details were worked out diff --git a/specifications/3.1.0/docs/about/purpose.md b/specifications/3.1.0/docs/about/purpose.md new file mode 100644 index 00000000..e65bf3fb --- /dev/null +++ b/specifications/3.1.0/docs/about/purpose.md @@ -0,0 +1,12 @@ + + +# Purpose + +The USEF Flex Trading protocol (UFTP) is a subset of the USEF framework. +Focused specifically on the exchange of flexibility between Aggregators (AGRs) and DSOs, it describes the corresponding market interactions between them to resolve grid constraints by applying congestion management or grid-capacity management. +UFTP can be used as a stand-alone protocol for flexibility forecasting, offering, ordering, and settlement processes. +Its purpose is to support the use of flexibility markets for grid-congestion issues and standardize the set-up and operation of these markets across different DSOs. diff --git a/specifications/3.1.0/docs/about/reading-guideline.md b/specifications/3.1.0/docs/about/reading-guideline.md new file mode 100644 index 00000000..c0529381 --- /dev/null +++ b/specifications/3.1.0/docs/about/reading-guideline.md @@ -0,0 +1,34 @@ + + +# Reading guideline + +The USEF Flexibility Trading Protocol Specification is accompanied by ‘USEF: The Framework explained’ [^B4] which provides insight into the background, scope and concepts underpinning USEF. +It is strongly advised that the USEF document is read in advance of this UFTP specification document. + +[^B4]: USEF Foundation, "USEF: The Framework Explained," USEF Foundation, Arnhem, 2015. + +USEF follows the principle of privacy & security by design and therefore the specifications are accompanied by a privacy & security guideline [^B5] which is applicable to the entire design, implementation and operation of USEF and derived products, services and solutions. + +[^B5]: USEF Foundation, "USEF: The Privacy and Security Guideline," USEF Foundation, Arnhem, 2015. Available: [https://www.usef.energy/app/uploads/2016/12/USEF_PrivacySecurityGuideline_3nov15.pdf](https://www.usef.energy/app/uploads/2016/12/USEF_PrivacySecurityGuideline_3nov15.pdf) + +The UFTP specifications consist of three main elements: + +- [General description](../general-description/index.md) +Informative description about usage of the protocol and process description for USEF’s market-based coordination mechanism + +- [Use case descriptions](../use-case-descriptions/scope.md) +Detailed descriptions of each process step of the process model, incl. scope & level, goal in context, preconditions, primary and secondary actors, the main scenario, etc. + +- [Message transport & descriptions](../message-descriptions/scope.md) +Syntax descriptions of all the messages required for the interfaces described in the framework, as well as detailed requirements for exchanging those messages. +A process description, including the specifications and rules that apply to each process, are provided. +A motivation for the design is included, wherever it is assumed beneficial. + +!!! success "Recommended Practice:" + + In order to make the universal descriptions of the framework applicable in practice and more comprehensible the specifications are accompanied by recommended practices. + These paragraphs are clearly indicated, in blue, throughout the specifications. diff --git a/docs/about/scope.md b/specifications/3.1.0/docs/about/scope.md similarity index 100% rename from docs/about/scope.md rename to specifications/3.1.0/docs/about/scope.md diff --git a/specifications/3.1.0/docs/appendix/bibliography.md b/specifications/3.1.0/docs/appendix/bibliography.md new file mode 100644 index 00000000..ca4af27b --- /dev/null +++ b/specifications/3.1.0/docs/appendix/bibliography.md @@ -0,0 +1,22 @@ + + +# Bibliography + +1. USEF, "Flexibility Value Chain (update 2018)," 8 10 2018. [Online]. Available: [https://www.usef.energy/app/uploads/2018/11/USEF-White-paper-Flexibility-Value-Chain-2018-version-1.0_Oct18.pdf](https://www.usef.energy/app/uploads/2018/11/USEF-White-paper-Flexibility-Value-Chain-2018-version-1.0_Oct18.pdf). +2. USEF, "White paper: Flexibility Platforms," 2 november 2018. [Online]. Available: [https://www.usef.energy/app/uploads/2018/11/USEF-White-Paper-Flexibility-Platforms-version-1.0_Nov2018.pdf](https://www.usef.energy/app/uploads/2018/11/USEF-White-Paper-Flexibility-Platforms-version-1.0_Nov2018.pdf). +3. USEF, "USEF - The FrameWork Specifications 2015," 2015. [Online]. +4. USEF Foundation, "USEF: The Framework Explained," USEF Foundation, Arnhem, 2015. +5. USEF Foundation, "USEF: The Privacy and Security Guideline," USEF Foundation, Arnhem, 2015. Available: [https://www.usef.energy/app/uploads/2016/12/USEF_PrivacySecurityGuideline_3nov15.pdf](https://www.usef.energy/app/uploads/2016/12/USEF_PrivacySecurityGuideline_3nov15.pdf) +6. USEF, "Recommended practices and key considerations for a regulatory framework and market design on explicit Demand Response," 2017. [Online]. Available: [https://www.usef.energy/app/uploads/2017/09/Recommended-practices-for-DR-market-design-2.pdf](https://www.usef.energy/app/uploads/2017/09/Recommended-practices-for-DR-market-design-2.pdf). +7. Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, ""Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616," 1999. +8. Bakke, M., Hafner, J., Hufferd, J., Voruganti, K., and M. Krueger, ""Internet Small Computer Systems Interface (iSCSI) Naming and Discovery", RFC 3721," 2004. +9. Satran, J., Meth, K., Sapuntzakis, C., Chadalapaka, M., and E. Zeidner, ""Internet Small Computer Systems Interface (iSCSI)", RFC 3720," 2004. +10. USEF Design Team, "Release Details USEF Specification 2014:I.I," USEF Foundation, Arnhem, 2014. +11. S. e. a. Tierney, "Pay-as-Bid vs. Uniform Pricing," Fortnightly Magazine, March 2008. +12. Wikipedia, "IEC 62056," 27 March 2014. [Online]. Available: [http://en.wikipedia.org/wiki/IEC_62056](http://en.wikipedia.org/wiki/IEC_62056). [Accessed 28 May 2014]. +13. P. v. Oirsouw, Netten voor distributie van electriciteit, Arnhem: Phase to Phase, 2012. +14. P. Mockapetris, ""Domain names - concepts and facilities", STD 13, RFC 1034," 1987. diff --git a/docs/appendix/flex-reservation-mechanism.md b/specifications/3.1.0/docs/appendix/flex-reservation-mechanism.md similarity index 100% rename from docs/appendix/flex-reservation-mechanism.md rename to specifications/3.1.0/docs/appendix/flex-reservation-mechanism.md diff --git a/docs/appendix/glossary.md b/specifications/3.1.0/docs/appendix/glossary.md similarity index 100% rename from docs/appendix/glossary.md rename to specifications/3.1.0/docs/appendix/glossary.md diff --git a/docs/appendix/message-transport-mechanism.md b/specifications/3.1.0/docs/appendix/message-transport-mechanism.md similarity index 100% rename from docs/appendix/message-transport-mechanism.md rename to specifications/3.1.0/docs/appendix/message-transport-mechanism.md diff --git a/specifications/3.1.0/docs/appendix/rationale-for-information-exchange-in-flexibility-request.md b/specifications/3.1.0/docs/appendix/rationale-for-information-exchange-in-flexibility-request.md new file mode 100644 index 00000000..29c0b90d --- /dev/null +++ b/specifications/3.1.0/docs/appendix/rationale-for-information-exchange-in-flexibility-request.md @@ -0,0 +1,29 @@ + + +# Rationale for information exchange in flexibility request + +USEF specifies that when sending a flexibility request, the DSO provides the following information about expected congestion. This appendix provides the rationale. + +- **Information about expected congestion is provided to all registered AGRs:** +The reduction required must be made available to all AGRs operating in the specific congestion area, due to the DSO’s legal obligation to treat all market parties in a non-discriminatory way. +The grid topology, however, is considered to be confidential information. +Therefore, USEF recommends that information about expected congestion is not provided freely to the entire market at national level. + +- **Information about expected congestion includes the direction of the overload (production/consumption):** +A grid overload at a congestion point can occur as a result of either too much production or too much consumption. +To reduce overload where there is too much production, either the production must be reduced, or the consumption must be increased. +For overload where there is too much consumption, this is the other way around (increase production or decrease consumption). +The implication is that the congestion information provided must be clear about the direction of the overload. + +- **Information about expected congestion includes the volume of reduction required.** +While it is sufficient for the DSO to provide only information about the need for reduction, rather than the volume of reduction required for an ISP, it makes sense to provide more detailed information as this is likely to result in a more optimal use of flexibility and therefore better usage of the grid. + +- **Information about expected congestion includes available grid capacity for other ISPs.** +Providing insight on the available grid capacity for the ISPs without congestion gives AGRs additional information that can be used to determine their flexibility offers. +In addition, it reduces the likelihood that the load shift provided by the AGRs will create a new peak that overloads the grid, and thus is likely to converge quicker, making the time needed to align a D-prognosis shorter. +Whether or not this time is needed mainly depends on the number of congestion points a DSO has defined. +On the downside, the more information provided by the DSO, the easier it is to get insight into the entire grid topology, especially for crucial points in the grid. diff --git a/docs/assets/images/README.md b/specifications/3.1.0/docs/assets/images/README.md similarity index 100% rename from docs/assets/images/README.md rename to specifications/3.1.0/docs/assets/images/README.md diff --git a/specifications/3.1.0/docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg b/specifications/3.1.0/docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg new file mode 100644 index 00000000..3190e973 --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg @@ -0,0 +1,3023 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -6 + + + + + -4 + + + + + -2 + + + + + 0 + + + + + 2 + + + + + 4 + + + + + 11 + + + + + 12 + + + + + 13 + + + + + 14 + + + + + 15 + + + + + 16 + + + + + FlexRequest + + + + + + Requested power exceeds + + + + + contracted power + + + + + + + + + + Requested power smaller than + + + + + contracted power + + + + + + + + Available + + + + + space: valid for + + + + + contract + + + + + + + + + + + + + + + + + + + + + + + -6 + + + + + -4 + + + + + -2 + + + + + 0 + + + + + 2 + + + + + 4 + + + + + 11 + + + + + 12 + + + + + 13 + + + + + 14 + + + + + 15 + + + + + 16 + + + + + Compliant FlexOffer + + + + + + Obligated + + + + + + + + + Free space + + + + + + + + diff --git a/specifications/3.1.0/docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg.license b/specifications/3.1.0/docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg.png b/specifications/3.1.0/docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg.png similarity index 100% rename from docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg.png rename to specifications/3.1.0/docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg.png diff --git a/docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg.png.license b/specifications/3.1.0/docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg.png.license similarity index 100% rename from docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg.png.license rename to specifications/3.1.0/docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg.png.license diff --git a/specifications/3.1.0/docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg b/specifications/3.1.0/docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg new file mode 100644 index 00000000..ef507f0e --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg @@ -0,0 +1,2878 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -6 + + + + + -4 + + + + + -2 + + + + + 0 + + + + + 2 + + + + + 4 + + + + + 11 + + + + + 12 + + + + + 13 + + + + + 14 + + + + + 15 + + + + + 16 + + + + + Contracted flex reservation + + + + + + + + + -6 + + + + + -4 + + + + + -2 + + + + + 0 + + + + + 2 + + + + + 4 + + + + + 11 + + + + + 12 + + + + + 13 + + + + + 14 + + + + + 15 + + + + + 16 + + + + + FlexReservationUpdate + + + + + + Reservation is set + + + + + + + + + Reservation is decreased + + + + + + + + + Reservation is released + + + + + + + + + + + + + + + + + + + + + + + diff --git a/specifications/3.1.0/docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg.license b/specifications/3.1.0/docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg.png b/specifications/3.1.0/docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg.png similarity index 100% rename from docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg.png rename to specifications/3.1.0/docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg.png diff --git a/docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg.png.license b/specifications/3.1.0/docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg.png.license similarity index 100% rename from docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg.png.license rename to specifications/3.1.0/docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg.png.license diff --git a/specifications/3.1.0/docs/assets/images/image1.png b/specifications/3.1.0/docs/assets/images/image1.png new file mode 100644 index 00000000..d8621621 Binary files /dev/null and b/specifications/3.1.0/docs/assets/images/image1.png differ diff --git a/specifications/3.1.0/docs/assets/images/image1.png.license b/specifications/3.1.0/docs/assets/images/image1.png.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image1.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.1.0/docs/assets/images/image13.emf b/specifications/3.1.0/docs/assets/images/image13.emf new file mode 100644 index 00000000..a252595d Binary files /dev/null and b/specifications/3.1.0/docs/assets/images/image13.emf differ diff --git a/specifications/3.1.0/docs/assets/images/image13.emf.license b/specifications/3.1.0/docs/assets/images/image13.emf.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image13.emf.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.1.0/docs/assets/images/image13.emf.odg b/specifications/3.1.0/docs/assets/images/image13.emf.odg new file mode 100644 index 00000000..bd7ca460 Binary files /dev/null and b/specifications/3.1.0/docs/assets/images/image13.emf.odg differ diff --git a/specifications/3.1.0/docs/assets/images/image13.emf.odg.license b/specifications/3.1.0/docs/assets/images/image13.emf.odg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image13.emf.odg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.1.0/docs/assets/images/image13.svg b/specifications/3.1.0/docs/assets/images/image13.svg new file mode 100644 index 00000000..261cdf24 --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image13.svg @@ -0,0 +1,3835 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0 + + + + + 1 + + + + + 0 + + + + + 2 + + + + + 0 + + + + + 3 + + + + + 0 + + + + + 1 + + + + + 2 + + + + + 3 + + + + + 4 + + + + + 5 + + + + + F + + + + + o + + + + + r + + + + + e + + + + + c + + + + + a + + + + + s + + + + + t + + + + + + + + + + + - + + + + + 5 + + + + + 0 + + + + + - + + + + + 3 + + + + + 0 + + + + + - + + + + + 1 + + + + + 0 + + + + + 1 + + + + + 0 + + + + + 1 + + + + + 2 + + + + + 3 + + + + + 4 + + + + + 5 + + + + + F + + + + + l + + + + + e + + + + + x + + + + + R + + + + + e + + + + + q + + + + + u + + + + + e + + + + + s + + + + + t + + + M + a + x + P + o + w + e + r + + M + i + n + P + o + w + e + r + + D + i + s + p + o + s + i + t + i + o + n + = + “ + R + e + q + u + e + s + t + e + d + ” + + D + i + s + p + o + s + i + t + i + o + n + = + “ + A + v + a + i + l + a + b + l + e + ” + + + + + + + + + diff --git a/specifications/3.1.0/docs/assets/images/image13.svg.license b/specifications/3.1.0/docs/assets/images/image13.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image13.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/assets/images/image13.svg.png b/specifications/3.1.0/docs/assets/images/image13.svg.png similarity index 100% rename from docs/assets/images/image13.svg.png rename to specifications/3.1.0/docs/assets/images/image13.svg.png diff --git a/docs/assets/images/image13.svg.png.license b/specifications/3.1.0/docs/assets/images/image13.svg.png.license similarity index 100% rename from docs/assets/images/image13.svg.png.license rename to specifications/3.1.0/docs/assets/images/image13.svg.png.license diff --git a/specifications/3.1.0/docs/assets/images/image14.emf b/specifications/3.1.0/docs/assets/images/image14.emf new file mode 100644 index 00000000..4976cc21 Binary files /dev/null and b/specifications/3.1.0/docs/assets/images/image14.emf differ diff --git a/specifications/3.1.0/docs/assets/images/image14.emf.license b/specifications/3.1.0/docs/assets/images/image14.emf.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image14.emf.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.1.0/docs/assets/images/image14.emf.odg b/specifications/3.1.0/docs/assets/images/image14.emf.odg new file mode 100644 index 00000000..506cf33d Binary files /dev/null and b/specifications/3.1.0/docs/assets/images/image14.emf.odg differ diff --git a/specifications/3.1.0/docs/assets/images/image14.emf.odg.license b/specifications/3.1.0/docs/assets/images/image14.emf.odg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image14.emf.odg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.1.0/docs/assets/images/image14.emf.odg.svg b/specifications/3.1.0/docs/assets/images/image14.emf.odg.svg new file mode 100644 index 00000000..41d2d45e --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image14.emf.odg.svg @@ -0,0 +1,250 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + day + - + 1 + + + + + + + + + + + + day + of delivery + + + + + + + + + + + time + window + day + - + ahead + trading + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + USEF + day + - + ahead + gate + closure + national + balacing + regime + gate + closure + + + + + + + + + + + + + + + 2h + + + + + + + + + \ No newline at end of file diff --git a/specifications/3.1.0/docs/assets/images/image14.emf.odg.svg.license b/specifications/3.1.0/docs/assets/images/image14.emf.odg.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image14.emf.odg.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/assets/images/image14.emf.odg.svg.png b/specifications/3.1.0/docs/assets/images/image14.emf.odg.svg.png similarity index 100% rename from docs/assets/images/image14.emf.odg.svg.png rename to specifications/3.1.0/docs/assets/images/image14.emf.odg.svg.png diff --git a/docs/assets/images/image14.emf.odg.svg.png.license b/specifications/3.1.0/docs/assets/images/image14.emf.odg.svg.png.license similarity index 100% rename from docs/assets/images/image14.emf.odg.svg.png.license rename to specifications/3.1.0/docs/assets/images/image14.emf.odg.svg.png.license diff --git a/specifications/3.1.0/docs/assets/images/image15.emf b/specifications/3.1.0/docs/assets/images/image15.emf new file mode 100644 index 00000000..7dfae79e Binary files /dev/null and b/specifications/3.1.0/docs/assets/images/image15.emf differ diff --git a/specifications/3.1.0/docs/assets/images/image15.emf.license b/specifications/3.1.0/docs/assets/images/image15.emf.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image15.emf.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.1.0/docs/assets/images/image15.emf.odg b/specifications/3.1.0/docs/assets/images/image15.emf.odg new file mode 100644 index 00000000..9af2a1c1 Binary files /dev/null and b/specifications/3.1.0/docs/assets/images/image15.emf.odg differ diff --git a/specifications/3.1.0/docs/assets/images/image15.emf.odg.license b/specifications/3.1.0/docs/assets/images/image15.emf.odg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image15.emf.odg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.1.0/docs/assets/images/image15.emf.odg.svg b/specifications/3.1.0/docs/assets/images/image15.emf.odg.svg new file mode 100644 index 00000000..451b563b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image15.emf.odg.svg @@ -0,0 +1,525 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + current + time 11:00 + pm + , gate + closure + for + ISP 1 + + + + + + + + + + + + + + ISP 5..94 + + + + + + + + + + + ISPs + 1..96 open + for + intraday + trading + + + + + + + + + + + + + 1h + + + + + + + + + + + 1 + + + + + + + + + + + 2 + + + + + + + + + + + 3 + + + + + + + + + + + 4 + + + + + + + + + + + 95 + + + + + + + + + + + 96 + + + + + + + + + + + + + + + + + ISPs + 3..96 open + for + intraday + trading + ISPs + 95..96 open + for + intraday + trading + + + + + + + + + + + + ISP 5..94 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + current time 11:30 + pm + , gate + closure + for + ISP 3 + + + + + + + + + + + + + 1h + + + + + + + + + + + + + 3 + + + + + + + + + + + 4 + + + + + + + + + + + 95 + + + + + + + + + + + 96 + + + + + + + + + + + + + + + + + + + + + ISP 5..94 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + current time 10:30 + pm + , gate + closure + for + ISP 95 + + + + + + + + + + + + + 1h + + + + + + + + + + + + + 3 + + + + + + + + + + + 4 + + + + + + + + + + + 95 + + + + + + + + + + + 96 + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/specifications/3.1.0/docs/assets/images/image15.emf.odg.svg.license b/specifications/3.1.0/docs/assets/images/image15.emf.odg.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image15.emf.odg.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/assets/images/image15.emf.odg.svg.png b/specifications/3.1.0/docs/assets/images/image15.emf.odg.svg.png similarity index 100% rename from docs/assets/images/image15.emf.odg.svg.png rename to specifications/3.1.0/docs/assets/images/image15.emf.odg.svg.png diff --git a/docs/assets/images/image15.emf.odg.svg.png.license b/specifications/3.1.0/docs/assets/images/image15.emf.odg.svg.png.license similarity index 100% rename from docs/assets/images/image15.emf.odg.svg.png.license rename to specifications/3.1.0/docs/assets/images/image15.emf.odg.svg.png.license diff --git a/specifications/3.1.0/docs/assets/images/image18.emf b/specifications/3.1.0/docs/assets/images/image18.emf new file mode 100644 index 00000000..bfa25563 Binary files /dev/null and b/specifications/3.1.0/docs/assets/images/image18.emf differ diff --git a/specifications/3.1.0/docs/assets/images/image18.emf.license b/specifications/3.1.0/docs/assets/images/image18.emf.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image18.emf.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.1.0/docs/assets/images/image18.emf.odg b/specifications/3.1.0/docs/assets/images/image18.emf.odg new file mode 100644 index 00000000..8d63146f Binary files /dev/null and b/specifications/3.1.0/docs/assets/images/image18.emf.odg differ diff --git a/specifications/3.1.0/docs/assets/images/image18.emf.odg.license b/specifications/3.1.0/docs/assets/images/image18.emf.odg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image18.emf.odg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.1.0/docs/assets/images/image18.emf.odg.svg b/specifications/3.1.0/docs/assets/images/image18.emf.odg.svg new file mode 100644 index 00000000..3989dd35 --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image18.emf.odg.svg @@ -0,0 +1,350 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Role + process + messages + (USEF + core + ) + + + + + + + + + + + Message transfer mechanism + (USEF + recommended + practice + ) + + + + + + + + + + + DNSSEC + + + + + + + + + + + SignedMessage + XM + L + + + + + + + + + + + Allow/deny lists + + + + + + + + + + + NaCl elliptic curve + encryption + + + + + + + + + + + Service discovery + + + + + + + + + + + HTTP+SSL + + + + + + + + + + + Recipient: Internet domain, USEF role + + + + + + + + + + + XML content as per + https://usef.energy/schema/2019/messaging.xsd + + + + + + + + + + + Authenticatio + n + + + + + + + + + + + Abuse + mitigation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Remove + USEF + participant + s + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/specifications/3.1.0/docs/assets/images/image18.emf.odg.svg.license b/specifications/3.1.0/docs/assets/images/image18.emf.odg.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image18.emf.odg.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/assets/images/image18.emf.odg.svg.png b/specifications/3.1.0/docs/assets/images/image18.emf.odg.svg.png similarity index 100% rename from docs/assets/images/image18.emf.odg.svg.png rename to specifications/3.1.0/docs/assets/images/image18.emf.odg.svg.png diff --git a/docs/assets/images/image18.emf.odg.svg.png.license b/specifications/3.1.0/docs/assets/images/image18.emf.odg.svg.png.license similarity index 100% rename from docs/assets/images/image18.emf.odg.svg.png.license rename to specifications/3.1.0/docs/assets/images/image18.emf.odg.svg.png.license diff --git a/specifications/3.1.0/docs/assets/images/image19.png b/specifications/3.1.0/docs/assets/images/image19.png new file mode 100644 index 00000000..9f69e99a Binary files /dev/null and b/specifications/3.1.0/docs/assets/images/image19.png differ diff --git a/specifications/3.1.0/docs/assets/images/image19.png.license b/specifications/3.1.0/docs/assets/images/image19.png.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image19.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.1.0/docs/assets/images/image2.png b/specifications/3.1.0/docs/assets/images/image2.png new file mode 100644 index 00000000..4e2d1d40 Binary files /dev/null and b/specifications/3.1.0/docs/assets/images/image2.png differ diff --git a/specifications/3.1.0/docs/assets/images/image2.png.license b/specifications/3.1.0/docs/assets/images/image2.png.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image2.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.1.0/docs/assets/images/image20.png b/specifications/3.1.0/docs/assets/images/image20.png new file mode 100644 index 00000000..3b8ffd45 Binary files /dev/null and b/specifications/3.1.0/docs/assets/images/image20.png differ diff --git a/specifications/3.1.0/docs/assets/images/image20.png.license b/specifications/3.1.0/docs/assets/images/image20.png.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image20.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.1.0/docs/assets/images/image21.png b/specifications/3.1.0/docs/assets/images/image21.png new file mode 100644 index 00000000..808befa1 Binary files /dev/null and b/specifications/3.1.0/docs/assets/images/image21.png differ diff --git a/specifications/3.1.0/docs/assets/images/image21.png.license b/specifications/3.1.0/docs/assets/images/image21.png.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image21.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.1.0/docs/assets/images/image22.png b/specifications/3.1.0/docs/assets/images/image22.png new file mode 100644 index 00000000..cf1641fd Binary files /dev/null and b/specifications/3.1.0/docs/assets/images/image22.png differ diff --git a/specifications/3.1.0/docs/assets/images/image22.png.license b/specifications/3.1.0/docs/assets/images/image22.png.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image22.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.1.0/docs/assets/images/image23.emf b/specifications/3.1.0/docs/assets/images/image23.emf new file mode 100644 index 00000000..9412d98b Binary files /dev/null and b/specifications/3.1.0/docs/assets/images/image23.emf differ diff --git a/specifications/3.1.0/docs/assets/images/image23.emf.license b/specifications/3.1.0/docs/assets/images/image23.emf.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image23.emf.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.1.0/docs/assets/images/image23.emf.odg b/specifications/3.1.0/docs/assets/images/image23.emf.odg new file mode 100644 index 00000000..ced3431f Binary files /dev/null and b/specifications/3.1.0/docs/assets/images/image23.emf.odg differ diff --git a/specifications/3.1.0/docs/assets/images/image23.emf.odg.license b/specifications/3.1.0/docs/assets/images/image23.emf.odg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image23.emf.odg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.1.0/docs/assets/images/image23.emf.odg.svg b/specifications/3.1.0/docs/assets/images/image23.emf.odg.svg new file mode 100644 index 00000000..51da9bc2 --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image23.emf.odg.svg @@ -0,0 +1,613 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Client + + + + + + + + + + + Server + + + + + + + + + + + 1. retrieve message from outbound queue + + + + + + + + + + + 2. determine USEF endpoint of recipient + + + + + + + + + + + 3. sign UTF + - + 8 representation using NaCl and + compose message to be transmitted + + + + + + + + + + + USEF XML message + + + + + + + + + + + DNS/configuration + + + + + + + + + + + private signing key + + + + + + + + + + + USEF XML SignedMessage: + - + Sender DNS Domain + - + Sender role + - + Base64 encoded NaCl sealed message + + + + + + + + + + + 4. post text/xml body over HTTPS + + + + + + + + + + + 5. check HTTP result code: + a. + Temporary + error? + b. + Permanent + error? + c. + Success? + + + + + + + + + + + 6. check XML result attribute: + d. + Rejected? + e. + Success? + + + + + + + + + + + + + + + + + + + + + + + + + + 7. update message status in outbound queue + a + . + Retry + later + * + b/d + Delivery + failed + e. + Waiting for reply + ( + * + unless message has expired then use scenario b) + + + + + + + + + + + + case c + case a/b + + + + + + + + + + + + + + + 1. check HTTP protocol requirements + + + + + + + + + + + 3. obtain public signing key; + unseal NaCl message + + + + + + + + + + + USEF XML schema + + + + + + + + + + + connection history + + + + + + + + + + + 4. validate received message + + + + + + + + + + + + + + + + + + + + + + + + + 5. store message in inbound message queue + + + + + + + + + + + + HTTP 200 OK + + + + + + + + + + + + + 2. parse XML SignedMessage + + + + + + + + + + + DNS/configuration + + + + + + + + + + + USEF XML message + + + + + + + + + + + configuration + + + + + + + + + + + + + F + + + + + + + + + + + F + + + + + + + + + + + F + + + + + + + + + + + F + + + + + + + + + + + + + + + + + F + + + + + + + + + + + + + + HTTP ERROR + (e.g. 400 Bad Request) + OK + + + + + + + + + + + + OK + Failure + OK + Failure + OK + Failure + Rejected + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/specifications/3.1.0/docs/assets/images/image23.emf.odg.svg.license b/specifications/3.1.0/docs/assets/images/image23.emf.odg.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image23.emf.odg.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/assets/images/image23.emf.odg.svg.png b/specifications/3.1.0/docs/assets/images/image23.emf.odg.svg.png similarity index 100% rename from docs/assets/images/image23.emf.odg.svg.png rename to specifications/3.1.0/docs/assets/images/image23.emf.odg.svg.png diff --git a/docs/assets/images/image23.emf.odg.svg.png.license b/specifications/3.1.0/docs/assets/images/image23.emf.odg.svg.png.license similarity index 100% rename from docs/assets/images/image23.emf.odg.svg.png.license rename to specifications/3.1.0/docs/assets/images/image23.emf.odg.svg.png.license diff --git a/specifications/3.1.0/docs/assets/images/image24.emf b/specifications/3.1.0/docs/assets/images/image24.emf new file mode 100644 index 00000000..f0481477 Binary files /dev/null and b/specifications/3.1.0/docs/assets/images/image24.emf differ diff --git a/specifications/3.1.0/docs/assets/images/image24.emf.license b/specifications/3.1.0/docs/assets/images/image24.emf.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image24.emf.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.1.0/docs/assets/images/image24.emf.odg b/specifications/3.1.0/docs/assets/images/image24.emf.odg new file mode 100644 index 00000000..5f8b51ac Binary files /dev/null and b/specifications/3.1.0/docs/assets/images/image24.emf.odg differ diff --git a/specifications/3.1.0/docs/assets/images/image24.emf.odg.license b/specifications/3.1.0/docs/assets/images/image24.emf.odg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image24.emf.odg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.1.0/docs/assets/images/image24.emf.odg.svg b/specifications/3.1.0/docs/assets/images/image24.emf.odg.svg new file mode 100644 index 00000000..21fccbe8 --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image24.emf.odg.svg @@ -0,0 +1,76 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/specifications/3.1.0/docs/assets/images/image24.emf.odg.svg.license b/specifications/3.1.0/docs/assets/images/image24.emf.odg.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image24.emf.odg.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/assets/images/image24.emf.odg.svg.png b/specifications/3.1.0/docs/assets/images/image24.emf.odg.svg.png similarity index 100% rename from docs/assets/images/image24.emf.odg.svg.png rename to specifications/3.1.0/docs/assets/images/image24.emf.odg.svg.png diff --git a/docs/assets/images/image24.emf.odg.svg.png.license b/specifications/3.1.0/docs/assets/images/image24.emf.odg.svg.png.license similarity index 100% rename from docs/assets/images/image24.emf.odg.svg.png.license rename to specifications/3.1.0/docs/assets/images/image24.emf.odg.svg.png.license diff --git a/specifications/3.1.0/docs/assets/images/image24.svg b/specifications/3.1.0/docs/assets/images/image24.svg new file mode 100644 index 00000000..24e3a69e --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image24.svg @@ -0,0 +1,2495 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + D + S + O + . + e + x + a + m + p + l + e + D + N + S + + + _ + U + S + E + F + + + _ + D + S + O + + + _ + C + R + O + + + T + X + T + + + C + N + A + M + E + + + T + X + T + + + C + N + A + M + E + + + A + / + A + A + A + A + + + + + D + S + O + - + a + f + f + i + l + i + a + t + e + d + - + A + g + g + r + e + g + a + t + o + r + - + 1 + . + e + x + a + m + p + l + e + D + N + S + + + T + X + T + + + C + N + A + M + E + + + _ + A + G + R + + + _ + U + S + E + F + + + + T + i + n + y + - + A + g + g + r + e + g + a + t + o + r + . + e + x + a + m + p + l + e + D + N + S + + + T + X + T + + + C + N + A + M + E + + + _ + U + S + E + F + + + _ + A + G + R + + + + + + + + S + S + L + + + + + + + diff --git a/specifications/3.1.0/docs/assets/images/image24.svg.license b/specifications/3.1.0/docs/assets/images/image24.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image24.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/assets/images/image24.svg.png b/specifications/3.1.0/docs/assets/images/image24.svg.png similarity index 100% rename from docs/assets/images/image24.svg.png rename to specifications/3.1.0/docs/assets/images/image24.svg.png diff --git a/docs/assets/images/image24.svg.png.license b/specifications/3.1.0/docs/assets/images/image24.svg.png.license similarity index 100% rename from docs/assets/images/image24.svg.png.license rename to specifications/3.1.0/docs/assets/images/image24.svg.png.license diff --git a/specifications/3.1.0/docs/assets/images/image25.png b/specifications/3.1.0/docs/assets/images/image25.png new file mode 100644 index 00000000..d17f652f Binary files /dev/null and b/specifications/3.1.0/docs/assets/images/image25.png differ diff --git a/specifications/3.1.0/docs/assets/images/image25.png.license b/specifications/3.1.0/docs/assets/images/image25.png.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image25.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.1.0/docs/assets/images/image3.emf b/specifications/3.1.0/docs/assets/images/image3.emf new file mode 100644 index 00000000..57cc04e4 Binary files /dev/null and b/specifications/3.1.0/docs/assets/images/image3.emf differ diff --git a/specifications/3.1.0/docs/assets/images/image3.emf.license b/specifications/3.1.0/docs/assets/images/image3.emf.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image3.emf.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.1.0/docs/assets/images/image3.emf.odg b/specifications/3.1.0/docs/assets/images/image3.emf.odg new file mode 100644 index 00000000..b8824ece Binary files /dev/null and b/specifications/3.1.0/docs/assets/images/image3.emf.odg differ diff --git a/specifications/3.1.0/docs/assets/images/image3.emf.odg.license b/specifications/3.1.0/docs/assets/images/image3.emf.odg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image3.emf.odg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.1.0/docs/assets/images/image3.emf.odg.svg b/specifications/3.1.0/docs/assets/images/image3.emf.odg.svg new file mode 100644 index 00000000..02cb08bb --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image3.emf.odg.svg @@ -0,0 +1,240 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + AGR + + + + + + + + + + + + + + + + DSO + + + + + + + + + + + + + + + + + + + + + + + + + + + + + bilateral trade + trade via market platform + + + + + + + + + + + + + AGR + + + + + + + + + + + + + + + + DSO + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Exchange + € + + + + + + + + + \ No newline at end of file diff --git a/specifications/3.1.0/docs/assets/images/image3.emf.odg.svg.license b/specifications/3.1.0/docs/assets/images/image3.emf.odg.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image3.emf.odg.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/assets/images/image3.emf.odg.svg.png b/specifications/3.1.0/docs/assets/images/image3.emf.odg.svg.png similarity index 100% rename from docs/assets/images/image3.emf.odg.svg.png rename to specifications/3.1.0/docs/assets/images/image3.emf.odg.svg.png diff --git a/docs/assets/images/image3.emf.odg.svg.png.license b/specifications/3.1.0/docs/assets/images/image3.emf.odg.svg.png.license similarity index 100% rename from docs/assets/images/image3.emf.odg.svg.png.license rename to specifications/3.1.0/docs/assets/images/image3.emf.odg.svg.png.license diff --git a/specifications/3.1.0/docs/assets/images/image4.emf b/specifications/3.1.0/docs/assets/images/image4.emf new file mode 100644 index 00000000..387e3eed Binary files /dev/null and b/specifications/3.1.0/docs/assets/images/image4.emf differ diff --git a/specifications/3.1.0/docs/assets/images/image4.emf.license b/specifications/3.1.0/docs/assets/images/image4.emf.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image4.emf.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.1.0/docs/assets/images/image4.emf.odg b/specifications/3.1.0/docs/assets/images/image4.emf.odg new file mode 100644 index 00000000..da43bb9e Binary files /dev/null and b/specifications/3.1.0/docs/assets/images/image4.emf.odg differ diff --git a/specifications/3.1.0/docs/assets/images/image4.emf.odg.license b/specifications/3.1.0/docs/assets/images/image4.emf.odg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image4.emf.odg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.1.0/docs/assets/images/image4.emf.odg.svg b/specifications/3.1.0/docs/assets/images/image4.emf.odg.svg new file mode 100644 index 00000000..21bd8023 --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image4.emf.odg.svg @@ -0,0 +1,239 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + AGR + + + + + + + + + + + + + + + + DSO + + + + + + + + + + + + + + + + + + + + + + + + + + + + + bilateral trade + flex trade + + + + + + + + + + + + + AGR + + + + + + + + + + + + + + + + DSO + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + TSO/DSO + coordination + platform + + + + + + + + + + + + flex needs + + + + + + + + + \ No newline at end of file diff --git a/specifications/3.1.0/docs/assets/images/image4.emf.odg.svg.license b/specifications/3.1.0/docs/assets/images/image4.emf.odg.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image4.emf.odg.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/assets/images/image4.emf.odg.svg.png b/specifications/3.1.0/docs/assets/images/image4.emf.odg.svg.png similarity index 100% rename from docs/assets/images/image4.emf.odg.svg.png rename to specifications/3.1.0/docs/assets/images/image4.emf.odg.svg.png diff --git a/docs/assets/images/image4.emf.odg.svg.png.license b/specifications/3.1.0/docs/assets/images/image4.emf.odg.svg.png.license similarity index 100% rename from docs/assets/images/image4.emf.odg.svg.png.license rename to specifications/3.1.0/docs/assets/images/image4.emf.odg.svg.png.license diff --git a/specifications/3.1.0/docs/assets/images/image5.png b/specifications/3.1.0/docs/assets/images/image5.png new file mode 100644 index 00000000..1d7de0b4 Binary files /dev/null and b/specifications/3.1.0/docs/assets/images/image5.png differ diff --git a/specifications/3.1.0/docs/assets/images/image5.png.license b/specifications/3.1.0/docs/assets/images/image5.png.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image5.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.1.0/docs/assets/images/image6.png b/specifications/3.1.0/docs/assets/images/image6.png new file mode 100644 index 00000000..41790e05 Binary files /dev/null and b/specifications/3.1.0/docs/assets/images/image6.png differ diff --git a/specifications/3.1.0/docs/assets/images/image6.png.license b/specifications/3.1.0/docs/assets/images/image6.png.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image6.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.1.0/docs/assets/images/image8.emf b/specifications/3.1.0/docs/assets/images/image8.emf new file mode 100644 index 00000000..4a9b36a7 Binary files /dev/null and b/specifications/3.1.0/docs/assets/images/image8.emf differ diff --git a/specifications/3.1.0/docs/assets/images/image8.emf.license b/specifications/3.1.0/docs/assets/images/image8.emf.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image8.emf.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.1.0/docs/assets/images/image8.emf.odg b/specifications/3.1.0/docs/assets/images/image8.emf.odg new file mode 100644 index 00000000..b2a3d2d2 Binary files /dev/null and b/specifications/3.1.0/docs/assets/images/image8.emf.odg differ diff --git a/specifications/3.1.0/docs/assets/images/image8.emf.odg.license b/specifications/3.1.0/docs/assets/images/image8.emf.odg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image8.emf.odg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/3.1.0/docs/assets/images/image8.emf.odg.svg b/specifications/3.1.0/docs/assets/images/image8.emf.odg.svg new file mode 100644 index 00000000..85e03c22 --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image8.emf.odg.svg @@ -0,0 +1,76 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/specifications/3.1.0/docs/assets/images/image8.emf.odg.svg.license b/specifications/3.1.0/docs/assets/images/image8.emf.odg.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/image8.emf.odg.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/assets/images/image8.emf.odg.svg.png b/specifications/3.1.0/docs/assets/images/image8.emf.odg.svg.png similarity index 100% rename from docs/assets/images/image8.emf.odg.svg.png rename to specifications/3.1.0/docs/assets/images/image8.emf.odg.svg.png diff --git a/docs/assets/images/image8.emf.odg.svg.png.license b/specifications/3.1.0/docs/assets/images/image8.emf.odg.svg.png.license similarity index 100% rename from docs/assets/images/image8.emf.odg.svg.png.license rename to specifications/3.1.0/docs/assets/images/image8.emf.odg.svg.png.license diff --git a/specifications/3.1.0/docs/assets/images/shapeshifter-horizontal-color.svg b/specifications/3.1.0/docs/assets/images/shapeshifter-horizontal-color.svg new file mode 100644 index 00000000..0ecadbee --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/shapeshifter-horizontal-color.svg @@ -0,0 +1,179 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/specifications/3.1.0/docs/assets/images/shapeshifter-horizontal-color.svg.license b/specifications/3.1.0/docs/assets/images/shapeshifter-horizontal-color.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/shapeshifter-horizontal-color.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/assets/images/shapeshifter-horizontal-color.svg.png b/specifications/3.1.0/docs/assets/images/shapeshifter-horizontal-color.svg.png similarity index 100% rename from docs/assets/images/shapeshifter-horizontal-color.svg.png rename to specifications/3.1.0/docs/assets/images/shapeshifter-horizontal-color.svg.png diff --git a/docs/assets/images/shapeshifter-horizontal-color.svg.png.license b/specifications/3.1.0/docs/assets/images/shapeshifter-horizontal-color.svg.png.license similarity index 100% rename from docs/assets/images/shapeshifter-horizontal-color.svg.png.license rename to specifications/3.1.0/docs/assets/images/shapeshifter-horizontal-color.svg.png.license diff --git a/specifications/3.1.0/docs/assets/images/shapeshifter-icon-color.svg b/specifications/3.1.0/docs/assets/images/shapeshifter-icon-color.svg new file mode 100644 index 00000000..4cf66ceb --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/shapeshifter-icon-color.svg @@ -0,0 +1,118 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/specifications/3.1.0/docs/assets/images/shapeshifter-icon-color.svg.license b/specifications/3.1.0/docs/assets/images/shapeshifter-icon-color.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/shapeshifter-icon-color.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/assets/images/shapeshifter-icon-color.svg.png b/specifications/3.1.0/docs/assets/images/shapeshifter-icon-color.svg.png similarity index 100% rename from docs/assets/images/shapeshifter-icon-color.svg.png rename to specifications/3.1.0/docs/assets/images/shapeshifter-icon-color.svg.png diff --git a/docs/assets/images/shapeshifter-icon-color.svg.png.license b/specifications/3.1.0/docs/assets/images/shapeshifter-icon-color.svg.png.license similarity index 100% rename from docs/assets/images/shapeshifter-icon-color.svg.png.license rename to specifications/3.1.0/docs/assets/images/shapeshifter-icon-color.svg.png.license diff --git a/specifications/3.1.0/docs/assets/images/shapeshifter-icon-white.svg b/specifications/3.1.0/docs/assets/images/shapeshifter-icon-white.svg new file mode 100644 index 00000000..37a343a5 --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/shapeshifter-icon-white.svg @@ -0,0 +1,110 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/specifications/3.1.0/docs/assets/images/shapeshifter-icon-white.svg.license b/specifications/3.1.0/docs/assets/images/shapeshifter-icon-white.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/3.1.0/docs/assets/images/shapeshifter-icon-white.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/docs/assets/images/shapeshifter-icon-white.svg.png b/specifications/3.1.0/docs/assets/images/shapeshifter-icon-white.svg.png similarity index 100% rename from docs/assets/images/shapeshifter-icon-white.svg.png rename to specifications/3.1.0/docs/assets/images/shapeshifter-icon-white.svg.png diff --git a/docs/assets/images/shapeshifter-icon-white.svg.png.license b/specifications/3.1.0/docs/assets/images/shapeshifter-icon-white.svg.png.license similarity index 100% rename from docs/assets/images/shapeshifter-icon-white.svg.png.license rename to specifications/3.1.0/docs/assets/images/shapeshifter-icon-white.svg.png.license diff --git a/docs/diagrams/contract-phase.puml b/specifications/3.1.0/docs/diagrams/contract-phase.puml similarity index 100% rename from docs/diagrams/contract-phase.puml rename to specifications/3.1.0/docs/diagrams/contract-phase.puml diff --git a/docs/diagrams/operate-phase.puml b/specifications/3.1.0/docs/diagrams/operate-phase.puml similarity index 100% rename from docs/diagrams/operate-phase.puml rename to specifications/3.1.0/docs/diagrams/operate-phase.puml diff --git a/docs/diagrams/plan-phase.puml b/specifications/3.1.0/docs/diagrams/plan-phase.puml similarity index 100% rename from docs/diagrams/plan-phase.puml rename to specifications/3.1.0/docs/diagrams/plan-phase.puml diff --git a/docs/diagrams/settle-phase.puml b/specifications/3.1.0/docs/diagrams/settle-phase.puml similarity index 100% rename from docs/diagrams/settle-phase.puml rename to specifications/3.1.0/docs/diagrams/settle-phase.puml diff --git a/docs/diagrams/use-case-3-1-exchange-of-congestions-points.puml b/specifications/3.1.0/docs/diagrams/use-case-3-1-exchange-of-congestions-points.puml similarity index 100% rename from docs/diagrams/use-case-3-1-exchange-of-congestions-points.puml rename to specifications/3.1.0/docs/diagrams/use-case-3-1-exchange-of-congestions-points.puml diff --git a/docs/diagrams/use-case-3-10-exchange-of-flexorder-direct.puml b/specifications/3.1.0/docs/diagrams/use-case-3-10-exchange-of-flexorder-direct.puml similarity index 100% rename from docs/diagrams/use-case-3-10-exchange-of-flexorder-direct.puml rename to specifications/3.1.0/docs/diagrams/use-case-3-10-exchange-of-flexorder-direct.puml diff --git a/docs/diagrams/use-case-3-10-exchange-of-flexorder.puml b/specifications/3.1.0/docs/diagrams/use-case-3-10-exchange-of-flexorder.puml similarity index 100% rename from docs/diagrams/use-case-3-10-exchange-of-flexorder.puml rename to specifications/3.1.0/docs/diagrams/use-case-3-10-exchange-of-flexorder.puml diff --git a/docs/diagrams/use-case-3-11-transmission-of-settlement.puml b/specifications/3.1.0/docs/diagrams/use-case-3-11-transmission-of-settlement.puml similarity index 100% rename from docs/diagrams/use-case-3-11-transmission-of-settlement.puml rename to specifications/3.1.0/docs/diagrams/use-case-3-11-transmission-of-settlement.puml diff --git a/docs/diagrams/use-case-3-2-exchange-of-connections-by-agr.puml b/specifications/3.1.0/docs/diagrams/use-case-3-2-exchange-of-connections-by-agr.puml similarity index 100% rename from docs/diagrams/use-case-3-2-exchange-of-connections-by-agr.puml rename to specifications/3.1.0/docs/diagrams/use-case-3-2-exchange-of-connections-by-agr.puml diff --git a/docs/diagrams/use-case-3-3-retrieval-of-congestion-points.puml b/specifications/3.1.0/docs/diagrams/use-case-3-3-retrieval-of-congestion-points.puml similarity index 100% rename from docs/diagrams/use-case-3-3-retrieval-of-congestion-points.puml rename to specifications/3.1.0/docs/diagrams/use-case-3-3-retrieval-of-congestion-points.puml diff --git a/docs/diagrams/use-case-3-4-retrieval-of-registered-connections.puml b/specifications/3.1.0/docs/diagrams/use-case-3-4-retrieval-of-registered-connections.puml similarity index 100% rename from docs/diagrams/use-case-3-4-retrieval-of-registered-connections.puml rename to specifications/3.1.0/docs/diagrams/use-case-3-4-retrieval-of-registered-connections.puml diff --git a/docs/diagrams/use-case-3-5-exchange-of-flexreservationupdate.puml b/specifications/3.1.0/docs/diagrams/use-case-3-5-exchange-of-flexreservationupdate.puml similarity index 100% rename from docs/diagrams/use-case-3-5-exchange-of-flexreservationupdate.puml rename to specifications/3.1.0/docs/diagrams/use-case-3-5-exchange-of-flexreservationupdate.puml diff --git a/docs/diagrams/use-case-3-6-exchange-of-d-prognoses.puml b/specifications/3.1.0/docs/diagrams/use-case-3-6-exchange-of-d-prognoses.puml similarity index 100% rename from docs/diagrams/use-case-3-6-exchange-of-d-prognoses.puml rename to specifications/3.1.0/docs/diagrams/use-case-3-6-exchange-of-d-prognoses.puml diff --git a/docs/diagrams/use-case-3-7-exchange-of-flexrequests.puml b/specifications/3.1.0/docs/diagrams/use-case-3-7-exchange-of-flexrequests.puml similarity index 100% rename from docs/diagrams/use-case-3-7-exchange-of-flexrequests.puml rename to specifications/3.1.0/docs/diagrams/use-case-3-7-exchange-of-flexrequests.puml diff --git a/docs/diagrams/use-case-3-8-exchange-of-flexoffers.puml b/specifications/3.1.0/docs/diagrams/use-case-3-8-exchange-of-flexoffers.puml similarity index 100% rename from docs/diagrams/use-case-3-8-exchange-of-flexoffers.puml rename to specifications/3.1.0/docs/diagrams/use-case-3-8-exchange-of-flexoffers.puml diff --git a/docs/diagrams/use-case-3-9-revocation-of-flexoffer.puml b/specifications/3.1.0/docs/diagrams/use-case-3-9-revocation-of-flexoffer.puml similarity index 100% rename from docs/diagrams/use-case-3-9-revocation-of-flexoffer.puml rename to specifications/3.1.0/docs/diagrams/use-case-3-9-revocation-of-flexoffer.puml diff --git a/docs/diagrams/validate-phase-direct-flexorder.puml b/specifications/3.1.0/docs/diagrams/validate-phase-direct-flexorder.puml similarity index 100% rename from docs/diagrams/validate-phase-direct-flexorder.puml rename to specifications/3.1.0/docs/diagrams/validate-phase-direct-flexorder.puml diff --git a/docs/diagrams/validate-phase-gate-closure-time.puml b/specifications/3.1.0/docs/diagrams/validate-phase-gate-closure-time.puml similarity index 100% rename from docs/diagrams/validate-phase-gate-closure-time.puml rename to specifications/3.1.0/docs/diagrams/validate-phase-gate-closure-time.puml diff --git a/docs/diagrams/validate-phase-multiple-flexoffers.puml b/specifications/3.1.0/docs/diagrams/validate-phase-multiple-flexoffers.puml similarity index 100% rename from docs/diagrams/validate-phase-multiple-flexoffers.puml rename to specifications/3.1.0/docs/diagrams/validate-phase-multiple-flexoffers.puml diff --git a/docs/diagrams/validate-phase.puml b/specifications/3.1.0/docs/diagrams/validate-phase.puml similarity index 100% rename from docs/diagrams/validate-phase.puml rename to specifications/3.1.0/docs/diagrams/validate-phase.puml diff --git a/docs/general-description/contract-phase.md b/specifications/3.1.0/docs/general-description/contract-phase.md similarity index 100% rename from docs/general-description/contract-phase.md rename to specifications/3.1.0/docs/general-description/contract-phase.md diff --git a/specifications/3.1.0/docs/general-description/index.md b/specifications/3.1.0/docs/general-description/index.md new file mode 100644 index 00000000..5928a06b --- /dev/null +++ b/specifications/3.1.0/docs/general-description/index.md @@ -0,0 +1,15 @@ + + +# General description + +This chapter describes the global information flows for flexibility trading between AGR and DSO for grid contraint purposes. +In this respect, UFTP acts as a subset of USEF’s market-based coordination mechanism (MCM), where AGR-DSO trading is an embedded part of the broader mechanism which applies to multiple flexibility services for all relevant market roles. +In order to understand how UFTP is embedded in USEF, we have used some of USEF’s general concepts to describe the UFTP processes. +For further information on these, please see ‘USEF: The Framework explained’ [^B1]. +Sections describe the interactions in the different Phases of MCM: [Contract](contract-phase.md), [Plan](plan-phase.md), [Validate](validate-phase.md), [Operate](operate-phase.md) and [Settle](settle-phase.md). + +[^B1]: USEF, "Flexibility Value Chain (update 2018)," 8 10 2018. [Online]. Available: [https://www.usef.energy/app/uploads/2018/11/USEF-White-paper-Flexibility-Value-Chain-2018-version-1.0_Oct18.pdf](https://www.usef.energy/app/uploads/2018/11/USEF-White-paper-Flexibility-Value-Chain-2018-version-1.0_Oct18.pdf). diff --git a/docs/general-description/operate-phase.md b/specifications/3.1.0/docs/general-description/operate-phase.md similarity index 100% rename from docs/general-description/operate-phase.md rename to specifications/3.1.0/docs/general-description/operate-phase.md diff --git a/docs/general-description/plan-phase.md b/specifications/3.1.0/docs/general-description/plan-phase.md similarity index 100% rename from docs/general-description/plan-phase.md rename to specifications/3.1.0/docs/general-description/plan-phase.md diff --git a/docs/general-description/settle-phase.md b/specifications/3.1.0/docs/general-description/settle-phase.md similarity index 100% rename from docs/general-description/settle-phase.md rename to specifications/3.1.0/docs/general-description/settle-phase.md diff --git a/specifications/3.1.0/docs/general-description/usef-general-concepts.md b/specifications/3.1.0/docs/general-description/usef-general-concepts.md new file mode 100644 index 00000000..3f7403ec --- /dev/null +++ b/specifications/3.1.0/docs/general-description/usef-general-concepts.md @@ -0,0 +1,101 @@ + + +# USEF general concepts + +## USEF market-based coordination mechanism (MCM) + +USEF’s MCM facilitates the delivery of value propositions (i.e. marketable services) to various market parties without imposing +limitations on the diversity and customization of the propositions. +The USEF MCM is designed for all energy commodities and enables the market to optimize in time, capacity and power. +The MCM provides access, under equal conditions, for all stakeholders to a single integrated market. +This unique approach aims to deliver a future-proof market design. The USEF MCM operations scheme distinguishes five phases: + +![](../assets/images/image5.png) + +In UFTP, the general MCM phases are followed. However, processes in each phase are limited to the interactions between the +AGR and DSO for flexibility trading. This includes interaction with the ‘Common Reference’: + +- **Contract:** AGR and DSO negotiate FlexOptions. +This is flexibility that is reserved for DSO purposes and can be invoked by the DSO when needed. +Typically, a contract includes availability remunerations and activation remunerations. + +- **Plan:** information exchange between DSO and AGRs related to congestion points. +This information exchange through the ‘Common Reference’ involves communication with the Common Reference Operator (CRO). +The AGR carries out an initial portfolio optimization. + +- **Validate:** the DSO uses D-prognoses to validate whether the demand and supply of energy can be distributed safely without any limitations. +If congestion occurs, the DSO can procure flexibility from AGRs to resolve grid capacity issues. + +- **Operate:** in the operate phase, the actual assets and appliances are dispatched and the AGR adheres to its D-prognoses. +When required, DSOs can invoke additional flexibility from AGRs to resolve unexpected congestion. + +- **Settle:** in the settle phase, the flexibility that the AGR has sold to DSOs is settled. +For this purpose, the actual consumed and produced volumes are allocated to the responsible parties first. +Any unresolved or disputed volumes are reconciled shortly afterwards. + +## USEF Operating regimes + +USEF recognizes four different operating regimes. +The green regime is the classical grid without any limitations (copper plate) and the red regime is where power outages occur. +USEF introduces two additional regimes. In the green and yellow regimes, the MCM assures optimal use of the flexibility available for BRPs (green and yellow) and DSOs (yellow). +The orange regime is introduced as a fallback for situations where there is insufficient flexibility available for the DSO to avoid an outage—the DSO can limit connections to temporarily overrule the market. + +
+ ![USEF Operating regimes](../assets/images/image6.png) +
USEF Operating regimes
+
+ + +UFTP flexibility trading takes place solely in the yellow regime. Full descriptions of all other regimes can be found in [^B3]. + +[^B3]: USEF, "USEF - The FrameWork Specifications 2015," 2015. [Online]. + +## Day-head and intraday flexiblity trading + +The plan and validate phases aim to make optimal use of flexibility and maximize the freedom of dispatch and transactions of all stakeholders before the actual delivery of energy takes place. +The timescale of these phases already ranges from years and months ahead, towards one day ahead and, ultimately, hours ahead before the actual delivery of energy (i.e. the operate phase) starts. +This broad time window supports trading on various energy markets (i.e. forward market, day-ahead spot market and intraday spot-market) and the monitoring of changes in the required grid capacity. + +USEF specifies that iterations between the plan and validate phases take place at least twice: initially, during the day ahead and, secondly, during intraday. +Hence, two points in time are determined when the markets close: 1) end of day-ahead 2) end of intraday. +This specification eases the iterative process of creating, aligning and converging plans and D-prognoses and fits well with many current national processes applied in the day ahead and intraday trading market. +Please find more details in [Iterations between the plan and validate phases](validate-phase.md#iterations-between-the-plan-and-validate-phases). + +UFTP supports both day-ahead and intraday trading. Intraday trading is optional for UFTP. + +## Congestions points + +A congestion point is a set of connections which (directly) relate to a part of the grid where grid capacity might be exceeded because it may be insufficient to distribute the requested amount of energy; e.g. the secondary side of an LV transformer. +Please note that a congestion point is a part of the grid where congestion may possibly occur, rather than actually occurs. +It is the DSOs responsibility to determine congestion points. + +!!! success "Recommended practice:" + + How to determine which grid points are congestion points is the DSOs responsibility and therefore outside of the scope of USEF. + However, USEF recommends declaring congestion points at the lowest possible level in the grid as this allows for detailed insight about local congestion while simultaneously, through aggregation, safeguarding the reliability of the grid safety analysis. + +Congestion points are registered in the common reference, see [Common Reference](contract-phase.md#common-reference). + +## Flexiblity market time granularity + +All flexibility exchange in USEF is based on a time granularity that is in line with the imbalance settlement period (ISP)[^2], which is the time unit for which the imbalance of the balance responsible parties is calculated. +For most EU countries this is a 15-minute interval, leading to 96 ISPs per day. +Forecasts, flexibility offers, and orders and settlement are all based on ISPs. +Flexibility is expressed in Power [Watts] which is to be interpreted as the average Power during an ISP. + +[^2]: Commission Regulation (EU) 2017/2195 of 23 November 2017 establishing a guideline on electricity balancing defines an imbalance settlement period (ISP) as the time unit for which the imbalance of the balance responsible parties is calculated (Article 2(10)). + +## Alternative baselines + +All flexibility trading in USEF assumes that flexibility offers take the form of deviation from baseline, i.e. the default situation that would occur if no flexibility were activated. +Typically, the baseline is derived via an AGR nomination referred to as the D-prognosis. +However, UFTP allows for alternative baseline, where a D-prognosis is not required, and it is assumed that the AGR and DSO agree upon the baseline. +An alternative baseline could be based on a measurement (MBMA-method), a mathematical formula or a reference group, etc. +The choice of the alternative baseline and its establishment is out-of-scope for UFTP. +The UFTP trading messages either refer to D-prognosis or to an external baseline reference. +Throughout this document, the D-prognosis is used as the default baseline method. +If UFTP is used with alternative baseline, then all references to the D-prognosis can be ignored. diff --git a/docs/general-description/validate-phase.md b/specifications/3.1.0/docs/general-description/validate-phase.md similarity index 100% rename from docs/general-description/validate-phase.md rename to specifications/3.1.0/docs/general-description/validate-phase.md diff --git a/specifications/3.1.0/docs/index.md b/specifications/3.1.0/docs/index.md new file mode 100644 index 00000000..8516ac6f --- /dev/null +++ b/specifications/3.1.0/docs/index.md @@ -0,0 +1,24 @@ + + +# USEF Flex Trading Protocol + +The Universal Smart Energy Framework (USEF) has been developed to drive a fast, fair and lowest cost route to an integrated smart energy future. +By delivering one common standard, it enables cost-efficient connectivity of all smart energy projects and technologies. +Its market structure, roles, rules and tools for the commoditization and trading of flexible energy usage work with existing energy markets. + +The USEF Flex Trading protocol (UFTP) is a subset of the USEF framework. +Focused specifically on the exchange of flexibility between Aggregators (AGRs) and DSOs, it describes the corresponding market interactions between them to resolve grid constraints by applying congestion management or grid-capacity management. +UFTP can be used as a stand-alone protocol for flexibility forecasting, offering, ordering, and settlement processes. + +UFTP and the USEF Framework were originally developed, maintained and audited by the USEF Foundation. +In 2021, USEF moved to the Linux Foundation Energy, and the project is rebranded as ‘Shapeshifter – a universal flex trading protocol’. + +## Intellectual property disclaimer + +This specification is provided to you "as is" with no warranties whatsoever, including any warranty of merchantability, non-infringement, or fitness for any particular purpose. +The authors of this specification disclaim all liability, including liability for infringement of any proprietary rights, relating to use or implementation of information in this specification. +The provision of this specification to you does not provide you with any license, express or implied, by estoppel or otherwise, to any intellectual property rights. diff --git a/docs/message-descriptions/message-catalog/agr-portfolio-query-response.md b/specifications/3.1.0/docs/message-descriptions/message-catalog/agr-portfolio-query-response.md similarity index 100% rename from docs/message-descriptions/message-catalog/agr-portfolio-query-response.md rename to specifications/3.1.0/docs/message-descriptions/message-catalog/agr-portfolio-query-response.md diff --git a/specifications/3.1.0/docs/message-descriptions/message-catalog/agr-portfolio-query.md b/specifications/3.1.0/docs/message-descriptions/message-catalog/agr-portfolio-query.md new file mode 100644 index 00000000..a88c0ac2 --- /dev/null +++ b/specifications/3.1.0/docs/message-descriptions/message-catalog/agr-portfolio-query.md @@ -0,0 +1,21 @@ + + +# AGRPortfolioQuery + +The AGRPortfolioQuery is used by the AGR to retrieve additional information on the connections. + +``` + +``` + +| | | +|----------|--------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see section [metadata attributes](metadata-attributes.md). | +| Period | The Period for which the AGR requests the portfolio information. | diff --git a/docs/message-descriptions/message-catalog/agr-portfolio-update-response.md b/specifications/3.1.0/docs/message-descriptions/message-catalog/agr-portfolio-update-response.md similarity index 100% rename from docs/message-descriptions/message-catalog/agr-portfolio-update-response.md rename to specifications/3.1.0/docs/message-descriptions/message-catalog/agr-portfolio-update-response.md diff --git a/specifications/3.1.0/docs/message-descriptions/message-catalog/agr-portfolio-update.md b/specifications/3.1.0/docs/message-descriptions/message-catalog/agr-portfolio-update.md new file mode 100644 index 00000000..1a7689d9 --- /dev/null +++ b/specifications/3.1.0/docs/message-descriptions/message-catalog/agr-portfolio-update.md @@ -0,0 +1,28 @@ + + +# AGRPortfolioUpdate + +The AGRPortfolioUpdate is used by the AGR to indicate on which Connections it represents prosumers. + +``` + +/> +``` + +| | | +|-----------------|------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| Connection | | +| ⇥ EntityAddress | EntityAddress of the Connection entity being updated. | +| ⇥ StartPeriod | The first Period hat the AGR represents the prosumer at this Connection. | +| ⇥ EndPeriod | The last Period that the AGR represents the prosumer at this Connection, if applicable. | diff --git a/docs/message-descriptions/message-catalog/d-prognosis-response.md b/specifications/3.1.0/docs/message-descriptions/message-catalog/d-prognosis-response.md similarity index 100% rename from docs/message-descriptions/message-catalog/d-prognosis-response.md rename to specifications/3.1.0/docs/message-descriptions/message-catalog/d-prognosis-response.md diff --git a/specifications/3.1.0/docs/message-descriptions/message-catalog/d-prognosis.md b/specifications/3.1.0/docs/message-descriptions/message-catalog/d-prognosis.md new file mode 100644 index 00000000..159a443d --- /dev/null +++ b/specifications/3.1.0/docs/message-descriptions/message-catalog/d-prognosis.md @@ -0,0 +1,38 @@ + + +# D-Prognosis + +D-Prognosis messages are used to communicate D-prognoses between AGRs and DSOs. +D-Prognosis messages always contain data for all ISPs for the period they apply to, even if a prognosis is sent after the start of the period, when one or more ISPs are already in the operate or settlement phase. +Receiving implementations should ignore the information supplied for those ISPs. + +``` + +/> +``` + +| | | +|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| Period | The Period this D-Prognosis applies to. | +| CongestionPoint | Entity Address of the Congestion Point this prognosis applies to. Required for D-prognoses, prohibited for other prognosis types. | +| Revision | Revision of this message. A sequence number that must be incremented each time a new revision of a prognosis is sent. The combination of SenderDomain and PrognosisSequence should be unique. | +| ISP | | +| ⇥ Power | Power specified for this ISP in Watts. Also see the important notes about the sign of this attribute in the main documentation entry for the Power attribute. | +| ⇥ Start | Number of the first ISP this element refers to. The first ISP of a day has number 1. | +| ⇥ Duration | The number of the ISPs this element represents. | + +Note: Every day-ahead D-Prognosis must contain a Power value for every single ISP of the specified Period. diff --git a/docs/message-descriptions/message-catalog/dso-portfolio-query-response.md b/specifications/3.1.0/docs/message-descriptions/message-catalog/dso-portfolio-query-response.md similarity index 100% rename from docs/message-descriptions/message-catalog/dso-portfolio-query-response.md rename to specifications/3.1.0/docs/message-descriptions/message-catalog/dso-portfolio-query-response.md diff --git a/specifications/3.1.0/docs/message-descriptions/message-catalog/dso-portfolio-query.md b/specifications/3.1.0/docs/message-descriptions/message-catalog/dso-portfolio-query.md new file mode 100644 index 00000000..d21adddb --- /dev/null +++ b/specifications/3.1.0/docs/message-descriptions/message-catalog/dso-portfolio-query.md @@ -0,0 +1,23 @@ + + +# DSOPortfolioQuery + +DSOPortfolioQuery is used by DSOs to discover which AGRs represent connections on its registered congestion point(s). + +``` + +``` + +| | | +|---------------|------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| EntityAddress | Entity Address of the CongestionPoint entity being queried. | +| Period | The Period being queried. | diff --git a/docs/message-descriptions/message-catalog/dso-portfolio-update-response.md b/specifications/3.1.0/docs/message-descriptions/message-catalog/dso-portfolio-update-response.md similarity index 100% rename from docs/message-descriptions/message-catalog/dso-portfolio-update-response.md rename to specifications/3.1.0/docs/message-descriptions/message-catalog/dso-portfolio-update-response.md diff --git a/specifications/3.1.0/docs/message-descriptions/message-catalog/dso-portfolio-update.md b/specifications/3.1.0/docs/message-descriptions/message-catalog/dso-portfolio-update.md new file mode 100644 index 00000000..d0d9ee64 --- /dev/null +++ b/specifications/3.1.0/docs/message-descriptions/message-catalog/dso-portfolio-update.md @@ -0,0 +1,43 @@ + + +# DSOPortfolioUpdate + +The DSOPortfolioUpdate is used by the DSO to indicate on which congestion points it wants to engage in flexibility trading. + +``` + + /> +/> +``` + +| | | +|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| CongestionPoint | | +| ⇥ EntityAddress | Entity Address of the CongestionPoint entity being updated. | +| ⇥ StartPeriod | The first Period that the DSO is trading on this CongestionPoint. | +| ⇥ EndPeriod | The last Period that the DSO is trading on this CongestionPoint. | +| ⇥ MutexOffersSupported | Indicates whether the DSO accepts mutual exclusive FlexOffers on this CongestionPoint | +| ⇥ DayAheadRedispatchBy | Indicates which party is responsible for day-ahead redispatch, AGR or DSO. | +| ⇥ IntradayRedispatchBy | Indicates which party is responsible for intraday ahead redispatch, AGR or DSO. If not specified, there will be no intraday trading on this CongestionPoint. | +| ⇥ Connection | | +| ⇥ ⇥ EntityAddress | Entity Address of a Connection that is part of this CongestionPoint. | +| ⇥ ⇥ StartPeriod | The first Period that the Connection is part of this CongestionPoint. Notes:
  • The StartPeriod of a Connection should be greater than or equal to the StartPeriod of the CongestionPoint.
  • The StartPeriod of a Connection should be smaller than or equal to the EndPeriod of the CongestionPoint.
  • CRO implementors may choose to explicitly check for this and reject updates that do not comply.
| +| ⇥ ⇥ EndPeriod | The last Period that the Connection is part of this CongestionPoint. Notes:
  • The EndPeriod of a Connection should be null if and only if the EndPeriod of the CongestionPoint is null.
    The EndPeriod of a Connection should be greater than or equal to the StartPeriod of the CongestionPoint.
  • The EndPeriod of a Connection should be smaller than or equal to the EndPeriod of the CongestionPoint.
  • CRO implementors may choose to explicitly check for this and reject updates that do not comply.
| diff --git a/docs/message-descriptions/message-catalog/flex-offer-response.md b/specifications/3.1.0/docs/message-descriptions/message-catalog/flex-offer-response.md similarity index 100% rename from docs/message-descriptions/message-catalog/flex-offer-response.md rename to specifications/3.1.0/docs/message-descriptions/message-catalog/flex-offer-response.md diff --git a/docs/message-descriptions/message-catalog/flex-offer-revocation-response.md b/specifications/3.1.0/docs/message-descriptions/message-catalog/flex-offer-revocation-response.md similarity index 100% rename from docs/message-descriptions/message-catalog/flex-offer-revocation-response.md rename to specifications/3.1.0/docs/message-descriptions/message-catalog/flex-offer-revocation-response.md diff --git a/specifications/3.1.0/docs/message-descriptions/message-catalog/flex-offer-revocation.md b/specifications/3.1.0/docs/message-descriptions/message-catalog/flex-offer-revocation.md new file mode 100644 index 00000000..88d17ad4 --- /dev/null +++ b/specifications/3.1.0/docs/message-descriptions/message-catalog/flex-offer-revocation.md @@ -0,0 +1,23 @@ + + +# FlexOfferRevocation + +The FlexOfferRevocation message is used by the AGR to revoke a FlexOffer previously sent to a DSO. +It voids the FlexOffer, even if its validity time has not yet expired. +Revocation is not allowed for FlexOffers that already have associated accepted FlexOrders. + +``` + +``` + +| | | +|--------------------|--------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| FlexOfferMessageID | MessageID of the FlexOffer message that is being revoked: this FlexOffer must have been accepted previously. | diff --git a/docs/message-descriptions/message-catalog/flex-offer.md b/specifications/3.1.0/docs/message-descriptions/message-catalog/flex-offer.md similarity index 100% rename from docs/message-descriptions/message-catalog/flex-offer.md rename to specifications/3.1.0/docs/message-descriptions/message-catalog/flex-offer.md diff --git a/docs/message-descriptions/message-catalog/flex-order-response.md b/specifications/3.1.0/docs/message-descriptions/message-catalog/flex-order-response.md similarity index 100% rename from docs/message-descriptions/message-catalog/flex-order-response.md rename to specifications/3.1.0/docs/message-descriptions/message-catalog/flex-order-response.md diff --git a/docs/message-descriptions/message-catalog/flex-order.md b/specifications/3.1.0/docs/message-descriptions/message-catalog/flex-order.md similarity index 100% rename from docs/message-descriptions/message-catalog/flex-order.md rename to specifications/3.1.0/docs/message-descriptions/message-catalog/flex-order.md diff --git a/docs/message-descriptions/message-catalog/flex-request-response.md b/specifications/3.1.0/docs/message-descriptions/message-catalog/flex-request-response.md similarity index 100% rename from docs/message-descriptions/message-catalog/flex-request-response.md rename to specifications/3.1.0/docs/message-descriptions/message-catalog/flex-request-response.md diff --git a/specifications/3.1.0/docs/message-descriptions/message-catalog/flex-request.md b/specifications/3.1.0/docs/message-descriptions/message-catalog/flex-request.md new file mode 100644 index 00000000..9e53a49e --- /dev/null +++ b/specifications/3.1.0/docs/message-descriptions/message-catalog/flex-request.md @@ -0,0 +1,45 @@ + + +# FlexRequest + +FlexRequest messages are used by DSOs to request flexibility from AGRs. +In addition to one or more ISP elements with Disposition=Requested, indicating the actual need to reduce consumption or production, the message should also include the remaining ISPs for the current period where Disposition=Available. + +``` + +/> +``` + +| | | +|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| Period | The Period this FlexRequest message applies to. | +| ContractID | Reference to the concerning contract, if applicable. The contract may be either bilateral or commoditized market contract. | +| ServiceType | Service type for this request, the service type determines response characteristics such as latency or asset participation type. Each contract may specify multiple service-types. | +| CongestionPoint | Entity Address of the Congestion Point this FlexRequest message applies to. | +| Revision | Revision of this message, a sequence number that must be incremented each time a new revision of a FlexRequest message is sent. | +| ExpirationDateTime | Date and time, including the time zone (ISO 8601 formatted as per [http://www.w3.org/TR/NOTE-datetime](http://www.w3.org/TR/NOTE-datetime)) until when the FlexRequest message is valid. | +| ISP | | +| ⇥ Disposition | indication whether the Power specified for this ISP represents available capacity or a request for reduction/increase.
At least one ISP should have Disposition = Requested | +| ⇥ MinPower | Lower bound for available/requested space to deviate from the baseline (in Watts).
For further explanation, see section [Flexibility trading between the AGR and DSO](../../general-description/validate-phase.md#flexibility-trading-between-the-agr-and-dso). Also see the important notes about the sign of this attribute in the ISP element, section [power](power.md). | +| ⇥ MaxPower | Upper bound for available/requested space to deviate from the baseline (in Watts).
For further explanation, see section [Flexibility trading between the AGR and DSO](../../general-description/validate-phase.md#flexibility-trading-between-the-agr-and-dso). Also see the important notes about the sign of this attribute in the ISP element, section [power](power.md). | +| ⇥ Start | Number of the first ISP this element refers to. The first ISP of a day has number 1. | +| ⇥ Duration | The number of the ISPs this element represents. Optional, default value is 1. | diff --git a/docs/message-descriptions/message-catalog/flex-reservation-update-response.md b/specifications/3.1.0/docs/message-descriptions/message-catalog/flex-reservation-update-response.md similarity index 100% rename from docs/message-descriptions/message-catalog/flex-reservation-update-response.md rename to specifications/3.1.0/docs/message-descriptions/message-catalog/flex-reservation-update-response.md diff --git a/specifications/3.1.0/docs/message-descriptions/message-catalog/flex-reservation-update.md b/specifications/3.1.0/docs/message-descriptions/message-catalog/flex-reservation-update.md new file mode 100644 index 00000000..10ff9125 --- /dev/null +++ b/specifications/3.1.0/docs/message-descriptions/message-catalog/flex-reservation-update.md @@ -0,0 +1,37 @@ + + +# FlexReservationUpdate + +For bilateral contracts, FlexReservationUpdate messages are used by DSOs to signal to an AGR which part of the contracted volume is still reserved and which part is not needed and may be used for other purposes. +For each ISP, a power value is given which indicates how much power is still reserved. Zero power means that no power is reserved for that ISP and the sign of the power indicates the direction. + +``` + +/> +``` + +| | | +|-----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see section [metadata attributes](metadata-attributes.md). | +| Period | The Period this FlexRequest message applies to. | +| CongestionPoint | Entity Address of the Congestion Point this FlexRequest message applies to. | +| ContractID | Reference to the bilateral contract in question. | +| Reference | Message reference, assigned by the DSO originating the FlexReservationUpdate. | +| ISP | | +| ⇥ Power | Remaining reserved power specified for this ISP in Watts. See important notes about the [flex reservation mechanism](../../appendix/flex-reservation-mechanism.md). | +| ⇥ Start | Number of the first ISP this element refers to. The first ISP of a day has number 1. | +| ⇥ Duration | The number of the ISPs this element represents. Optional, default value is 1. | diff --git a/docs/message-descriptions/message-catalog/flex-settlement-response.md b/specifications/3.1.0/docs/message-descriptions/message-catalog/flex-settlement-response.md similarity index 100% rename from docs/message-descriptions/message-catalog/flex-settlement-response.md rename to specifications/3.1.0/docs/message-descriptions/message-catalog/flex-settlement-response.md diff --git a/specifications/3.1.0/docs/message-descriptions/message-catalog/flex-settlement.md b/specifications/3.1.0/docs/message-descriptions/message-catalog/flex-settlement.md new file mode 100644 index 00000000..6bc7cdcb --- /dev/null +++ b/specifications/3.1.0/docs/message-descriptions/message-catalog/flex-settlement.md @@ -0,0 +1,92 @@ + + +# FlexSettlement + +The FlexSettlement message is sent by DSOs on a regular basis (typically monthly) to AGRs, in order to initiate settlement. +It includes a list of all FlexOrders placed by the originating party during the settlement period. + +``` + + /> + + /> + /> +/> +``` + + +| | | +|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| PeriodStart | First Period of the settlement period this message applies to. | +| PeriodEnd | Last Period of the settlement period this message applies to. | +| Currency | ISO 4217 code indicating the currency that applies to all amounts (flex price, penalty and net settlement) in this message. | +| FlexOrderSettlement | | +| ⇥ Period | Period the FlexOrder refers to. | +| ⇥ ContractID | Reference to the concerning bilateral contract, if it is linked to it. | +| ⇥ MessageID | MessageID of the Prognosis message (more specifically: the D-Prognosis) the FlexOrder is based on, if it has been agreed that the baseline is based on D-prognoses. | +| ⇥ BaselineReference | Identification of the baseline prognosis, if another baseline methodology is used than based on D-prognoses. | +| ⇥ OrderReference | Order reference assigned by the DSO when originating the FlexOrder. | +| ⇥ CongestionPoint | Entity Address of the Congestion Point the FlexOrder applies to. | +| ⇥ Price | The price accepted for supplying the ordered amount of flexibility as per the referenced FlexOrder messages. | +| ⇥ Penalty | Optional (default zero) penalty due a non-zero PowerDeficiency. | +| ⇥ NetSettlement | Net settlement amount for this Period: Price minus Penalty | +| ⇥ ISP | | +| ⇥ ⇥ Start | Number of the first ISP this element refers to. The first ISP of a day has number 1. | +| ⇥ ⇥ Duration | The number of ISPs this element represents. Optional, default value is 1. | +| ⇥ ⇥ BaselinePower | Power originally forecast (as per the referenced baseline) for this ISP in Watts. | +| ⇥ ⇥ OrderedFlexPower | Amount of flex power ordered (as per the referenced FlexOrder message) for this ISP in Watts. | +| ⇥ ⇥ ActualPower | Actual amount of power for this ISP in Watts, as measured/determined by the DSO and allocated to the AGR. | +| ⇥ ⇥ DeliveredFlexPower | Actual amount of flex power delivered for this ISP in Watts, as determined by the DSO. | +| ⇥ ⇥ PowerDeficiency | Optional (default zero) amount of flex power sold but not delivered for this ISP in Watts, as determined by the DSO. | +| ContractSettlement | | +| ⇥ ContractID | Reference to the bilateral contract in question. | +| ⇥ Period | List of periods containing reservations | +| ⇥ ⇥ Period | Period the settlement refers to. | +| ⇥ ⇥ ISP | | +| ⇥ ⇥ ⇥ Start | Number of the first ISP this element refers to. The first ISP of a day has number 1. | +| ⇥ ⇥ ⇥ Duration | The number of ISPs this element represents. Optional, default value is 1. | +| ⇥ ⇥ ⇥ ReservedPower | Amount of flex power that has been reserved (and not released using a FlexReservationUpdate message) | +| ⇥ ⇥ ⇥ RequestedPower | Amount of flex power that has been both reserved in advance and has been requested using a FlexRequest (i.e. the lowest amount of flex power for this ISP). If there was no FlexRequest, this field is omitted. | +| ⇥ ⇥ ⇥ AvailablePower | Amount of flex power that is considered available based on the FlexRequest in question.
In case RequestedPower=0, AvailablePower is defined so that the offered power is allowed to be between 0 and AvailablePower in terms of compliancy (see [Flex reservation mechanism](../../appendix/flex-reservation-mechanism.md) for details).
In case RequestedPower ≠0, AvailablePower is defined so that the offered power is allowed to exceed the amount of requested power up to AvailablePower.
If this is relevant for settlement, the DSO can include this field. | +| ⇥ ⇥ ⇥ OfferedPower | Amount of flex power that has been reserved in advance, requested using a FlexRequest and covered in an offer from the AGR. If there was no offer, this field is omitted. If there were multiple offers, only the one is considered that is most compliant (see [Flex reservation mechanism](../../appendix/flex-reservation-mechanism.md) for details about compliancy). | +| ⇥ ⇥ ⇥ OrderedPower | Amount of flex power that has been ordered using a FlexOrder message that was based on a FlexOffer, both linked to this contract. If there was no order, this field is omitted. | diff --git a/specifications/3.1.0/docs/message-descriptions/message-catalog/index.md b/specifications/3.1.0/docs/message-descriptions/message-catalog/index.md new file mode 100644 index 00000000..09f9a299 --- /dev/null +++ b/specifications/3.1.0/docs/message-descriptions/message-catalog/index.md @@ -0,0 +1,13 @@ + + +# Message catalog + +USEF messages consist of XML, use UTF-8 encoding, and should validate against the USEF schema corresponding to the specification version implemented by a participant. +The current version of this schema, as well as historic production versions are available for download from the [Shapeshifter Github](https://github.com/shapeshifter/shapeshifter-specification). +Message types can be differentiated using the name of their root node. + +To allow extensibility as well as forward and backward compatibility of XML messages, the USEF schema allows additional elements in each defined sequence, as long as these elements have an explicit, non-default XML namespace. diff --git a/docs/message-descriptions/message-catalog/metadata-attributes.md b/specifications/3.1.0/docs/message-descriptions/message-catalog/metadata-attributes.md similarity index 100% rename from docs/message-descriptions/message-catalog/metadata-attributes.md rename to specifications/3.1.0/docs/message-descriptions/message-catalog/metadata-attributes.md diff --git a/docs/message-descriptions/message-catalog/metering-response.md b/specifications/3.1.0/docs/message-descriptions/message-catalog/metering-response.md similarity index 100% rename from docs/message-descriptions/message-catalog/metering-response.md rename to specifications/3.1.0/docs/message-descriptions/message-catalog/metering-response.md diff --git a/specifications/3.1.0/docs/message-descriptions/message-catalog/metering.md b/specifications/3.1.0/docs/message-descriptions/message-catalog/metering.md new file mode 100644 index 00000000..b27a7354 --- /dev/null +++ b/specifications/3.1.0/docs/message-descriptions/message-catalog/metering.md @@ -0,0 +1,50 @@ + + +# Metering + +The Metering message is an optional message. +The DSO will specify whether metering messages are required for a given program. +If metering messages are used then the AGR must send metering messages, with one message sent per connection point per day. +The metering messages must all be sent before the settlement can be performed. +It is recommend to send the metering messages daily, once the metering data has been collected for the day. + +``` + + /> +/> +``` + +The profile types to use will be agreed between the DSO and AGR and all agreed profile types must be included. +It is recommended to include the Power profile and in a following major version the Power profile will become a mandatory profile. + +Note: _The power profile represents the average active power during ISP, considering both import and export energy. +Power=(ImportEnergy-ExportEnergy)*(60/ISP-Length-Minutes). +For example with a 15 minute ISP length we have a multiplier of 4, with a 30 minute ISP length we have a multiplier of 2._ + + +| | | +|---------------|---------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see section [metadata attributes](metadata-attributes.md) | +| Period | The day that the metering data covers | +| EAN | The connection ID which this data refers to | +| Profile | A profile carries a sequence of ISPs with a defined type of metering data | +| ⇥ ProfileType | A value from the ProfileType enum, one of Power, ImportEnergy, ExportEnergy, ImportMeterReading, ExportMeterReading | +| ⇥ Unit | MeteringUnit type, use kW for Power and kWh for energy profile types. | +| ⇥ ISP | | +| ⇥ ⇥ Start | Number of the ISP this element refers to. The first ISP of a day has number 1. | +| ⇥ ⇥ Value | Metering, energy or price value at the end of this ISP, in the designated profile units | diff --git a/specifications/3.1.0/docs/message-descriptions/message-catalog/power.md b/specifications/3.1.0/docs/message-descriptions/message-catalog/power.md new file mode 100644 index 00000000..ec66669e --- /dev/null +++ b/specifications/3.1.0/docs/message-descriptions/message-catalog/power.md @@ -0,0 +1,15 @@ + + +# Power + +Power values occur in many USEF messages. +The sign of a power value is used to distinguish between production and consumption, from the perspective of the prosumer. +A positive value indicates that power flows towards the prosumer (consumption), a negative value indicates flow towards the grid (production). +The following statements are true for ISP elements in all USEF messages: + +- Each ISP in a period may only be addressed once. +- ISP elements may not cross period boundaries. diff --git a/specifications/3.1.0/docs/message-descriptions/message-catalog/signed-message.md b/specifications/3.1.0/docs/message-descriptions/message-catalog/signed-message.md new file mode 100644 index 00000000..081ea54c --- /dev/null +++ b/specifications/3.1.0/docs/message-descriptions/message-catalog/signed-message.md @@ -0,0 +1,26 @@ + + +# SignedMessage + +The SignedMessage element represents the secure wrapper used to submit USEF XML messages from the local message queue to the message queue of a remote participant. +It contains minimal metadata (which is distinct from the common metadata used for all other messages), allowing the recipient to look up the sender's cryptographic scheme and public keys, and the actual XML message, as transformed (signed/sealed) using that cryptographic scheme. + +XML representation summary + +``` + +``` + +| | | +|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| SenderDomain | The Internet domain of the USEF participant sending this message. Upon receiving a message, the recipient should validate that its value matches the corresponding attribute value specified in the inner XML message, once un-sealed: if not, the message must be rejected as invalid.
Domain name matching regular expression `^([a-z0-9]+(-[a-z0-9]+)*\.)+[a-z]{2,}$` | +| SenderRole | The USEF role of the participant sending this message: AGR, CRO or DSO. Receive-time validation should take place as described for the SenderDomain attribute above. The USEF specification identifies additional roles such as BRP and MDC. These are however not in scope of UFTP. | +| Body | The Base-64 encoded inner XML message contained in this wrapper, as transformed (signed/sealed) using the sender's cryptographic scheme. The recipient can determine which scheme applies using a DNS or configuration file lookup, based on the combination of SenderDomain and SenderRole. | diff --git a/docs/message-descriptions/message-catalog/test-message-response.md b/specifications/3.1.0/docs/message-descriptions/message-catalog/test-message-response.md similarity index 100% rename from docs/message-descriptions/message-catalog/test-message-response.md rename to specifications/3.1.0/docs/message-descriptions/message-catalog/test-message-response.md diff --git a/specifications/3.1.0/docs/message-descriptions/message-catalog/test-message.md b/specifications/3.1.0/docs/message-descriptions/message-catalog/test-message.md new file mode 100644 index 00000000..7a1cd160 --- /dev/null +++ b/specifications/3.1.0/docs/message-descriptions/message-catalog/test-message.md @@ -0,0 +1,21 @@ + + +# TestMessage + +TestMessage does not have any content (other than the mandatory metadata) and may be used by implementations for (connectivity) testing purposes. + +XML representation summary + +``` + +``` + +| | | +|----------|------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | diff --git a/docs/message-descriptions/scope.md b/specifications/3.1.0/docs/message-descriptions/scope.md similarity index 100% rename from docs/message-descriptions/scope.md rename to specifications/3.1.0/docs/message-descriptions/scope.md diff --git a/specifications/3.1.0/docs/use-case-descriptions/common-concepts.md b/specifications/3.1.0/docs/use-case-descriptions/common-concepts.md new file mode 100644 index 00000000..1b1f6a28 --- /dev/null +++ b/specifications/3.1.0/docs/use-case-descriptions/common-concepts.md @@ -0,0 +1,26 @@ + + +# Common concepts + +The USEF specification standardizes the logical interfaces and defines the minimum functionality of the components in the form of use cases (this chapter) and [message transport specifications](../appendix/message-transport-mechanism.md) and [message descriptions](../message-descriptions/scope.md). +This leaves room for innovation and possibilities to develop specific implementation architectures based on e.g. size of the market, specific local circumstances or commercial exploitation of USEF platforms. +Stakeholders involved in a USEF market can and must develop business functions and capabilities independently, and focus on their core business and competitive advantage. + +While the USEF specification is technology and implementation agnostic, there are some basic principles to which any USEF implementation architecture must adhere. +Some of these are listed as high-level requirements. +When an ICT implementation architecture is defined, the actual implementation requirements must be defined and included in the design. + +- A USEF market implementation will typically consist of multiple information systems interacting together according to the USEF interaction standard in order to run the market processes. +The USEF foundation does not want to narrow down the open nature of the USEF specifications by defining exactly how the information system architecture must be implemented. +- The USEF specifications do not currently define exceptions and how to handle them. +Therefore, the use cases also prescribe only the default main scenario without error handling, and only the successful outcome. +The single exception to this rule is described in the next bullet. +USEF does provide some recommended practices for handling some of the failure handling. +- Any USEF IT architecture must adhere to the USEF privacy & security guideline.[^B5] +In the USEF use cases the most relevant privacy & security considerations are provided. + +[^B5]: USEF Foundation, "USEF: The Privacy and Security Guideline," USEF Foundation, Arnhem, 2015. Available: [https://www.usef.energy/app/uploads/2016/12/USEF_PrivacySecurityGuideline_3nov15.pdf](https://www.usef.energy/app/uploads/2016/12/USEF_PrivacySecurityGuideline_3nov15.pdf) diff --git a/docs/use-case-descriptions/message-validation.md b/specifications/3.1.0/docs/use-case-descriptions/message-validation.md similarity index 100% rename from docs/use-case-descriptions/message-validation.md rename to specifications/3.1.0/docs/use-case-descriptions/message-validation.md diff --git a/specifications/3.1.0/docs/use-case-descriptions/privacy-and-security-by-design.md b/specifications/3.1.0/docs/use-case-descriptions/privacy-and-security-by-design.md new file mode 100644 index 00000000..aac6b580 --- /dev/null +++ b/specifications/3.1.0/docs/use-case-descriptions/privacy-and-security-by-design.md @@ -0,0 +1,32 @@ + + +# Privacy and security by design + +USEF – like most complex information systems – deals with sensitive data and therefore requires security and privacy preservation measures. +Privacy & security are system-wide issues; protection of individual subsystems/components is not enough; the system is as strong as the weakest link. +USEF therefore follows the principle of privacy & security by design. + +USEF provides a separate privacy and security guideline [^B5] that lists approximately 50 design principles which, combined, present a complete view of the privacy and security aspects associated with smart energy systems. +It takes into account the current legal and social views on privacy & security and links these to the future directions in which they will likely evolve. + +[^B5]: USEF Foundation, "USEF: The Privacy and Security Guideline," USEF Foundation, Arnhem, 2015. Available: [https://www.usef.energy/app/uploads/2016/12/USEF_PrivacySecurityGuideline_3nov15.pdf](https://www.usef.energy/app/uploads/2016/12/USEF_PrivacySecurityGuideline_3nov15.pdf) + +The guideline forms the basis for the logical security architecture that is reflected in USEF’s process flows and use cases. +Some remarks about security and responsibility: + +- Personal and personally identifiable data represent commercially sensitive information. These include: + - connection identifiers + - existence of congestion points + - details on AGRs associated to a connection + - portfolio data + - forecast data, content of D-prognoses and the fact whether or not a given AGR submitted a D-prognosis in a timely fashion + - the existence, content and timing of a flexibility request and other flexibility trading messages + - settlement items, including the acknowledgement or disputation of their correctness +- Personal and personally identifiable data (such as forecasts or smart meter readings) should not be retained longer than strictly required. The retention period should be specified and be communicated to the data subject. +- The exact identity of the AGR for each connection should not be disclosed to the DSO. Instead, only aggregate connection counts should be provided (which represent commercially sensitive information). +- It is the responsibility of the CRO to have policies regarding access, data retention, data security and conflict resolution compliant with the USEF privacy & security guidelines. +- The CRO should only disclose the existence of the congestion point on a need-to-know basis, i.e. only to those AGRs which provide an associated connection identifier in their queries. diff --git a/specifications/3.1.0/docs/use-case-descriptions/reading-guidelines.md b/specifications/3.1.0/docs/use-case-descriptions/reading-guidelines.md new file mode 100644 index 00000000..cce12bab --- /dev/null +++ b/specifications/3.1.0/docs/use-case-descriptions/reading-guidelines.md @@ -0,0 +1,19 @@ + + +# Reading guidelines + +This chapter contains separate sections per USEF phase: Plan, Validate, Operate, and Settle. +In each section the use cases are specified in a standard table format: + +_Standard table format for USEF use cases._ + +| | | +|------------------------|------------------------------------------------------------------------------------------------------------------------------| +| **Goal in context** | High-level description of the activity. | +| **Preconditions** | The state of the system that must be present prior to a use case being performed. | +| **Successful outcome** | The state the system will be in immediately after a use case has finished without failure. | +| **Failure outcome** | The state the system will be in immediately after a use case has finished after failure, plus identification of the failure. | diff --git a/specifications/3.1.0/docs/use-case-descriptions/scope.md b/specifications/3.1.0/docs/use-case-descriptions/scope.md new file mode 100644 index 00000000..02d9a534 --- /dev/null +++ b/specifications/3.1.0/docs/use-case-descriptions/scope.md @@ -0,0 +1,30 @@ + + +# Scope + +This chapter provides details of the functions that contain interactions relevant to the DSO and AGR, in order to be active in the USEF MCM. +To be USEF compliant, these functions must be implemented according to the use case descriptions in this chapter. + +The use cases have been derived from the MCM sequence diagrams detailed in Chapter [General description](../general-description/index.md). +Use cases are separate activities that require interaction between DSO and AGR, each containing multiple messages in both directions. +DSO and AGR internal processes are not addressed in this chapter. + +The messages types that occur in these use cases are mentioned and further described in Section [Message catalog](../message-descriptions/message-catalog/index.md). + +## Introduction + +The core of the USEF specification is the MCM and the processes governing it. +These define how the different stakeholders active in the MCM should behave and interact. +All use cases related to these functions are described to the extent relevant for the USEF specifications. +All aspects not specified by USEF are explicitly mentioned. +An example of this is that USEF does not specify how an AGR optimizes its portfolio or determines how much flexibility is available, where or when. +The result of this portfolio optimization is, however, a prerequisite for participating in the flexibility bidding process. + +For the flexibility market to function, it is essential to have a functioning common reference populated with all AGR-represented connections. + +Given the open nature of the USEF specifications, any implementation can choose to adopt all or only part of the specifications. +In any situation, all participants within a single USEF market will have to adopt a common specification of the market processes and information exchange. diff --git a/docs/use-case-descriptions/use-cases/contract-phase.md b/specifications/3.1.0/docs/use-case-descriptions/use-cases/contract-phase.md similarity index 100% rename from docs/use-case-descriptions/use-cases/contract-phase.md rename to specifications/3.1.0/docs/use-case-descriptions/use-cases/contract-phase.md diff --git a/specifications/3.1.0/docs/use-case-descriptions/use-cases/operate-phase.md b/specifications/3.1.0/docs/use-case-descriptions/use-cases/operate-phase.md new file mode 100644 index 00000000..059a91e2 --- /dev/null +++ b/specifications/3.1.0/docs/use-case-descriptions/use-cases/operate-phase.md @@ -0,0 +1,182 @@ + + +# Operate phase + +In [Operate phase](../../general-description/operate-phase.md) the informative description of the operate phase processes are provided. +In this chapter, the use cases will be described as derived from the operate phase. + +The USEF MCM operate phase specifies the following use cases: + +_Use cases for the operate phase._ + +| Name | Direction | Message types | +|---------------------------------------------------------------|-----------|---------------------------------------------------| +| [Exchange updated D-Prognoses](#exchange-updated-d-prognoses) | AGR → DSO | Prognosis / PrognosisResponse | +| [Revocation Flexibility Offer](#revocation-flexibility-offer) | AGR → DSO | FlexOfferRevocation / FlexOfferRevocationResponse | +| [Exchange Flexibility Orders](#exchange-flexibility-orders) | AGR ← DSO | FlexOrder / FlexOrderResponse | + +The use cases are explained in the following sections. + +## Exchange updated D-Prognoses + +The process diagram is similar to the figure in [Exchange D-Prognoses per Congestion Point](validate-phase.md#exchange-d-prognoses-per-congestion-point). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
D-prognosis
Goal in contextChanges in D-prognoses to be realized are transmitted.
PreconditionsAGR has created initial D-prognoses in the Plan/Validate phases, and has subsequently detected deviations in Operate that resulted in a portfolio state that requires those prognoses to be re-created.
Successful outcomePrognosis sent to DSO that reflects all relevant changes
Failure outcomeRejectionReasonCause of rejection
<See Message validation>D-prognosis failed to pass validation by the DSO
Lacking ISPsThe prognosis does not include all ISPs in the Period it applies to
Power value rejectionOne or more Power values in the prognosis are not plausible
Subordinate sequence numberThe message sequence is lower than that of a previously received D-prognosis
[User defined]Any other reasonable cause to reject the message
+ +### Related information + +The process is similar to that described in [Exchange D-Prognoses per Congestion Point](validate-phase.md#exchange-d-prognoses-per-congestion-point). +Deviations can be caused by new flexibility orders from the DSO and by unforeseen change of behavior by assets. + +The basic process for re-creating D-prognoses is the same as that used to create them in the first place, in the plan/validate phases. +When re-creating prognoses in the operate phase, values for ISPs that are already in the past should remain unchanged, as these will be ignored by DSOs anyway. + +## Revocation Flexibility Offer + +The process diagram is similar to the figure in [Revocation of FlexOffer](validate-phase.md#revocation-flexibility-offer). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Revoke FlexOffer
Goal in contextInform the DSO that a previously sent flexibility offer is no longer valid, despite the validity period of the offer not having expired yet.
PreconditionsA flexibility offer has been sent to and acknowledged by the DSO
Successful outcomeFlexibility offer revocation notification submitted to the DSO
Failure outcomeRejectionReasonCause of rejection
<See Message validation>FlexOfferRevocation failed to pass validation by the DSO
Flexibility procuredThe FlexOffer cannot be revoked because its flexibility has already been ordered
[User defined]Any other reasonable cause to reject the message
+ +### Related information + +The process is similar to that described in [Revocation Flexibility Offer](validate-phase.md#revocation-flexibility-offer). + +Flexibility offers may be revoked in the operate phase provided that none of the ISPs in the period the offer applies to are +already in, or past, the operate phase. + +## Exchange Flexibility Orders + +This process is triggered when flexibility is required to resolve congestion detected during the operate phase. +This might, for example, be the case when the prognoses change after the validate phase and there are still FlexOffers available. + +The process diagram is similar to the figure in [Exchange Flexibility Orders](validate-phase.md#exchange-flexibility-orders). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Revoke FlexOrder
Goal in contextAccept (some) flexibility offers to solve congestion during Operate phase.
PreconditionsCongestion detected while monitoring the grid, corresponding FlexOffer has been received and accepted by DSO and is still valid.
Successful outcomeFlexibility procured
Failure outcomeRejectionReasonCause of rejection
<See Message validation>FlexOrder failed to pass validation by the AGR
ISP mismatchISPs from the FlexOrder do not match the ISPs given in the FlexOffer
Power mismatchOrdered flexibility does not match the offered flexibility
Price mismatchPrice in the order does not match the price given in the offer
[User defined]Any other reasonable cause to reject the message
+ +### Related information + +The process is similar to that described in [Exchange Flexibility Orders](validate-phase.md#exchange-flexibility-orders). +Note that where a FlexOrder is rejected, manual processing is unlikely to result in timely resolution at this stage. +Note that although the updated D-prognosis is unlikely to be of immediate use to the DSO, it’s definitely required for settlement. diff --git a/docs/use-case-descriptions/use-cases/plan-phase.md b/specifications/3.1.0/docs/use-case-descriptions/use-cases/plan-phase.md similarity index 100% rename from docs/use-case-descriptions/use-cases/plan-phase.md rename to specifications/3.1.0/docs/use-case-descriptions/use-cases/plan-phase.md diff --git a/docs/use-case-descriptions/use-cases/settle-phase.md b/specifications/3.1.0/docs/use-case-descriptions/use-cases/settle-phase.md similarity index 100% rename from docs/use-case-descriptions/use-cases/settle-phase.md rename to specifications/3.1.0/docs/use-case-descriptions/use-cases/settle-phase.md diff --git a/docs/use-case-descriptions/use-cases/validate-phase.md b/specifications/3.1.0/docs/use-case-descriptions/use-cases/validate-phase.md similarity index 100% rename from docs/use-case-descriptions/use-cases/validate-phase.md rename to specifications/3.1.0/docs/use-case-descriptions/use-cases/validate-phase.md diff --git a/specifications/3.1.0/docs/versions.md b/specifications/3.1.0/docs/versions.md new file mode 100644 index 00000000..299e2c9a --- /dev/null +++ b/specifications/3.1.0/docs/versions.md @@ -0,0 +1,19 @@ + + +# Versioned specification files + +The XSD links below point to immutable version snapshots in the repository. The v3 PDF and Word files are the original artifacts from their respective release tags. + +| Version | Markdown and images | XSD files | PDF | Word | +| --- | --- | --- | --- | --- | +| 1.0.1 | Not archived | [Browse XSDs](https://github.com/shapeshifter/shapeshifter-specification/tree/main/specifications/1.0.1/xsd) | Not archived | Not archived | +| 2.0.0 | Not archived | [Browse XSDs](https://github.com/shapeshifter/shapeshifter-specification/tree/main/specifications/2.0.0/xsd) | Not archived | Not archived | +| 3.0.0 | [Browse docs](https://github.com/shapeshifter/shapeshifter-specification/tree/main/specifications/3.0.0/docs) | [Browse XSDs](https://github.com/shapeshifter/shapeshifter-specification/tree/main/specifications/3.0.0/xsd) | [Download PDF](https://github.com/shapeshifter/shapeshifter-specification/blob/main/specifications/3.0.0/USEF%20Flex%20Trading%20Protocol%20Specifications%203.0.0.pdf?raw=1) | [Download Word](https://github.com/shapeshifter/shapeshifter-specification/blob/main/specifications/3.0.0/USEF%20Flex%20Trading%20Protocol%20Specifications%203.0.0.docx?raw=1) | +| 3.1.0 | [Browse docs](https://github.com/shapeshifter/shapeshifter-specification/tree/main/specifications/3.1.0/docs) | [Browse XSDs](https://github.com/shapeshifter/shapeshifter-specification/tree/main/specifications/3.1.0/xsd) | [Download PDF](https://github.com/shapeshifter/shapeshifter-specification/blob/main/specifications/3.1.0/USEF%20Flex%20Trading%20Protocol%20Specifications%203.1.0.pdf?raw=1) | [Download Word](https://github.com/shapeshifter/shapeshifter-specification/blob/main/specifications/3.1.0/USEF%20Flex%20Trading%20Protocol%20Specifications.docx?raw=1) | +| Development | [Browse docs](https://github.com/shapeshifter/shapeshifter-specification/tree/main/specifications/development/docs) | [Browse XSDs](https://github.com/shapeshifter/shapeshifter-specification/tree/main/specifications/development/xsd) | Not published | Not published | + +The header version selector links to the published documentation versions. The current draft is published at `/development/` and is not a numbered release. \ No newline at end of file diff --git a/specifications/3.1.0/xsd/UFTP-agr-cro.xsd b/specifications/3.1.0/xsd/UFTP-agr-cro.xsd new file mode 100644 index 00000000..0544ac8a --- /dev/null +++ b/specifications/3.1.0/xsd/UFTP-agr-cro.xsd @@ -0,0 +1,167 @@ + + + + + + + + + + + + + + + Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. + + + + + + + + + + + A connection that the AGR want the CRO to update + + + + EntityAddress of the Connection entity being updated. + + + + + The first Period hat the AGR represents the prosumer at this Connection. + + + + + The last Period that the AGR represents the prosumer at this Connection, if applicable. + + + + + + + + + + + + MessageID of the AGRPortfolioUpdate that has just been accepted or rejected + + + + + + + + + + + + + + Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. + + + + + The Period for which the AGR requests the portfolio information. + + + + + + + + + + + + + + + + + Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. + + + + + MessageID of the AGRPortfolioQuery that has just been accepted or rejected + + + + + The Period that the portfolio is valid. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + EntityAddress of the CongestionPoint. + + + + + Indicates whether the DSO accepts mutual exclusive FlexOffers on this CongestionPoint. + + + + + Indicates which party is responsible for day-ahead redispatch. + + + + + Indicates which party is responsible for intraday ahead redispatch, AGR or DSO. If not specified, there will be no intraday trading on this CongestionPoint. + + + + + + + + + + EntityAddress of the Connection. + + + + + + + + + + + diff --git a/specifications/3.1.0/xsd/UFTP-agr-dso.xsd b/specifications/3.1.0/xsd/UFTP-agr-dso.xsd new file mode 100644 index 00000000..a936a3d4 --- /dev/null +++ b/specifications/3.1.0/xsd/UFTP-agr-dso.xsd @@ -0,0 +1,705 @@ + + + + + + + + + + + + + + ISO 8601 time interval (minutes only, for example PT15M) indicating the duration of the ISPs referenced in this message. Although the ISP length is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant ISP duration. + + + + + Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. + + + + + Day (in yyyy-mm-dd format) the ISPs referenced in this Flex* message belong to. + + + + + Entity Address of the Congestion Point this D-Prognosis applies to. + + + + + + + + + + + + + + The ISP represents one or more Imbalance Settlement Periods and is used by Prognosis and Flex-related messages. + + + + + + Revision of this message. A sequence number that must be incremented each time a new revision of a + prognosis is sent. The combination of SenderDomain and PrognosisSequence should be unique + + + + + + + + + + + + Power specified for this ISP in Watts. Also see the important notes about the sign of this attribute in the main documentation entry for the ISP element. + + + + + Number of the first ISPs this element refers to. The first ISP of a day has number 1. + + + + + The number of the ISPs this element represents. Optional, default value is 1. + + + + + + + + + + + + + + + + + + + + + + MessageID of the D-Prognosis message this request is based on. + + + + + + + + + + + + + + The ISP represents one or more Imbalance Settlement Periods and is used by Prognosis and Flex-related messages. + + + + + + Reference to the bilateral contract in question. + + + + + Message reference, assigned by the DSO originating the FlexReservationUpdate. + + + + + + + + + + + + Remaining reserved power specified for this ISP in Watts. + + + + + Number of the first ISPs this element refers to. The first ISP of a day has number 1. + + + + + The number of the ISPs this element represents. Optional, default value is 1. + + + + + + + + + + + + MessageID of the FlexReservationUpdate message this request is based on. + + + + + + + + + + + + + + The ISP represents one or more Imbalance Settlement Periods and is used by Prognosis and Flex-related messages. + + + + + + Revision of this message, a sequence number that must be incremented each time a new revision of a + FlexRequest message is sent. + + + + + Date and time, including the time zone (ISO 8601 formatted as per http://www.w3.org/TR/NOTE-datetime) until which the FlexRequest message is valid. + + + + + Reference to the concerning contract, if applicable. The contract may be either bilateral or commoditized market contract. Each contract may specify multiple service-types. + + + + + Service type for this request, the service type determines response characteristics such as latency or asset participation type. + + + + + + + + + + + + + Power specified for this ISP in Watts. Also see the important notes about the sign of this attribute in the main documentation entry for the ISP element. + + + + + Power specified for this ISP in Watts. Also see the important notes about the sign of this attribute in the main documentation entry for the ISP element. + + + + + Number of the first ISPs this element refers to. The first ISP of a day has number 1. + + + + + The number of the ISPs this element represents. Optional, default value is 1. + + + + + + + + + + + + MessageID of the FlexRequest message this request is based on. + + + + + + + + + + + + + + If the DSO does not support mutually exclusive offers it will reject FlexOffers that contain more than one OfferOption. + + + + + + Date and time, including the time zone (ISO 8601 formatted as per http://www.w3.org/TR/NOTE-datetime) until which the FlexOffer is valid. + + + + + Indicates whether this FlexOffer is intended to be unsolicited (i.e. without a preceding FlexRequest). + + + + + MessageID of the FlexRequest message this request is based on. Mandatory if Unsolicited=false. + + + + + Reference to the concerning contract, if applicable. The contract may be either bilateral or commoditized market contract. + + + + + MessageID of the D-Prognosis this request is based on, if it has been agreed that the baseline is based on D-prognoses. + + + + + Identification of the baseline prognosis, if another baseline methodology is used than based on D-prognoses + + + + + ISO 4217 code indicating the currency that applies to the price of the FlexOffer. + + + + + + + + + + + + The ISP represents one or more Imbalance Settlement Periods and is used by Prognosis and Flex-related messages. + + + + + + The identification of this option. + + + + + The asking price for the flexibility offered in this option. + + + + + The minimal activation factor for this OfferOption. An AGR may choose to include MinActivationFactor in FlexOffers even if the DSO is not interested in partial activation. In that case the DSO will simply use an ActivationFactor of 1.00 in every FlexOrder. + + + + + + + + + + Power specified for this ISP in Watts. Also see the important notes about the sign of this attribute in the main documentation entry for the ISP element. + + + + + Number of the first ISPs this element refers to. The first ISP of a day has number 1. + + + + + The number of the ISPs this element represents. Optional, default value is 1. + + + + + + + + + + MessageID of the FlexOffer message this request is based on. + + + + + + + + + + + + MessageID of the FlexOffer message that is being revoked: this FlexOffer must have been accepted previously. + + + + + + + + + + + + MessageID of the FlexOfferRevocation message this request is based on. + + + + + + + + + + + + The ISP represents one or more Imbalance Settlement Periods and is used by Prognosis and Flex-related messages. + + + + + + Indicates whether this FlexOrder is intended to be unsolicited (i.e. without a preceding FlexOffer). + + + + + MessageID of the FlexOffer message this order is based on. Mandatory if Unsolicited=false. + + + + + Service type for this order, the service type determines response characteristics such as latency or asset participation type. + + + + + Reference to the concerning bilateral contract, if applicable. + + + + + MessageID of the D-Prognosis this request is based on, if it has been agreed that the baseline is based on D-prognoses. + + + + + Identification of the baseline prognosis, if another baseline methodology is used than based on D-prognoses + + + + + The price for the flexibility ordered. Usually, the price should match the price of the related FlexOffer. + + + + + ISO 4217 code indicating the currency that applies to the price of the FlexOffer. + + + + + Order number assigned by the DSO originating the FlexOrder. To be stored by the AGR and used in the settlement phase. + + + + + The OptionReference from the OfferOption chosen from the FlexOffer, if applicable. + + + + + The activation factor for this OfferOption. The ActivationFactor must be greater than or equal to the MinActivationFactor in the OfferOption chosen from the FlexOffer. + + + + + + + + + + Power specified for this ISP in Watts. Also see the important notes about the sign of this attribute in the main documentation entry for the ISP element. + + + + + Number of the first ISPs this element refers to. The first ISP of a day has number 1. + + + + + The number of the ISPs this element represents. Optional, default value is 1. + + + + + + + + + + MessageID of the FlexOrder that has just been accepted or rejected. + + + + + + + + + + + + + + + + First Period of the settlement period this message applies to. + + + + + Last Period of the settlement period this message applies to. + + + + + ISO 4217 code indicating the currency that applies to all amounts (flex price, penalty and net settlement) in this message. + + + + + + + + + + + + + Order reference assigned by the DSO when originating the FlexOrder. + + + + + + + + + + Reference to the concerning bilateral contract, if it is linked to it + + + + + MessageID of the Prognosis message (more specifically: the D-Prognosis) the FlexOrder is based on, if it has been agreed that the baseline is based on D-prognoses. + + + + + Identification of the baseline prognosis, if another baseline methodology is used than based on D-prognoses. + + + + + Entity Address of the Congestion Point the FlexOrder applies to. + + + + + The price accepted for supplying the ordered amount of flexibility as per the referenced FlexOrder messages. + + + + + Penalty due a non-zero PowerDeficiency + + + + + Net settlement amount for this Period: Price minus Penalty. + + + + + + + + Number of the first ISPs this element refers to. The first ISP of a day has number 1. + + + + + The number of the ISPs this element represents. Optional, default value is 1. + + + + + Power originally forecast (as per the referenced baseline) for this ISP in Watts. + + + + + Amount of flex power ordered (as per the referenced FlexOrder message) for this ISP in Watts. + + + + + Actual amount of power for this ISP in Watts, as measured/determined by the DSO and allocated to the AGR. + + + + + + Actual amount of flex power delivered for this ISP in Watts, as determined by the DSO. + + + + + Amount of flex power sold but not delivered for this ISP in Watts, as determined by the DSO. + + + + + + + + + + The ISP represents one or more Imbalance Settlement Periods and is used by Prognosis and Flex-related messages. + + + + + + MessageID of the FlexSettlement message that has just been accepted or rejected + + + + + + + + + + Order reference assigned by the DSO when originating the FlexOrder. + + + + + Indication whether the AGR accepts the order settlement details provided by the DSO (and will invoice accordingly), or disputes these details. + + + + + In case the order settlement was disputed, this attribute must contain a human-readable description of the reason. + + + + + + + + + + + + + + Reference to the concerning bilateral contract. + + + + + + + + + + + Period the being settled. + + + + + + + + Number of the first ISPs this element refers to. The first ISP of a day has number 1. + + + + + The number of the ISPs this element represents. Optional, default value is 1. + + + + + Amount of flex power that has been reserved (and not released using a FlexReservationUpdate message). + + + + + Amount of flex power that has been both reserved in advance and has been requested using a + FlexRequest (i.e. the lowest amount of flex power for this ISP). If there was no FlexRequest, + this field is omitted. + + + + + Amount of flex power that is considered available based on the FlexRequest in question. In case RequestedPower=0, AvailablePower is defined so that the offered power is allowed to be between 0 and AvailablePower in terms of compliancy (see Appendix 3 for details). In case RequestedPower ≠0, AvailablePower is defined so that the offered power is allowed to exceed the amount of requested power up to AvailablePower. If this is relevant for settlement, the DSO can include this field. + + + + + Amount of flex power that has been reserved in advance, requested using a FlexRequest and covered in an offer from the AGR. If there was no offer, this field is omitted. If there were multiple offers, only the one is considered that is most compliant . + + + + + Amount of flex power that has been ordered using a FlexOrder message that was based on a FlexOffer, both linked to this contract. If there was no order, this field is omitted. + + + + + + + + + + + + + + + + + + + diff --git a/specifications/3.1.0/xsd/UFTP-agr.xsd b/specifications/3.1.0/xsd/UFTP-agr.xsd new file mode 100644 index 00000000..0c1c9202 --- /dev/null +++ b/specifications/3.1.0/xsd/UFTP-agr.xsd @@ -0,0 +1,6 @@ + + + + + + diff --git a/specifications/3.1.0/xsd/UFTP-common.xsd b/specifications/3.1.0/xsd/UFTP-common.xsd new file mode 100644 index 00000000..69dd8dcd --- /dev/null +++ b/specifications/3.1.0/xsd/UFTP-common.xsd @@ -0,0 +1,229 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The SignedMessage element represents the secure wrapper used to submit USEF XML messages from the local message queue to the message queue of a remote participant. It contains minimal metadata (which is distinct from the common metadata used for all other messages), allowing the recipient to look up the sender's cryptographic scheme and public keys, and the actual XML message, as transformed (signed/sealed) using that cryptographic scheme. + + + + The Internet domain of the USEF participant sending this message. Upon receiving a message, the recipient should validate that its value matches the corresponding attribute value specified in the inner XML message, once un-sealed: if not, the message must be rejected as invalid. + + + + + The USEF role of the participant sending this message: AGR, BRP, CRO, DSO or MDC. Receive-time validation should take place as described for the SenderDomain attribute above. + + + + + The Base-64 encoded inner XML message contained in this wrapper, as transformed (signed/sealed) using the sender's cryptographic scheme. The recipient can determine which scheme applies using a DNS or configuration file lookup, based on the combination of SenderDomain and SenderRole. + + + + + + + + + + Version of the Shapeshifter specification used by the USEF participant sending this message. + + + + + The Internet domain of the USEF participant sending this message. When receiving a message, its value should match the value specified in the SignedMessage wrapper: otherwise, the message must be rejected as invalid. When replying to this message, this attribute is used to look up the USEF endpoint the reply message should be delivered to. + + + + + Internet domain of the participant this message is intended for. When sending a message, this attribute, combined with the RecipientRole, is used to look up the USEF endpoint the message should be delivered to. + + + + + Date and time this message was created, including the time zone (ISO 8601 formatted as per http://www.w3.org/TR/NOTE-datetime). + + + + + Unique identifier (UUID/GUID as per IETF RFC 4122) for this message, to be generated when composing each message. + + + + + Unique identifier (UUID/GUID as per IETF RFC 4122) used to correlate responses with requests, to be generated when composing the first message in a conversation and subsequently copied from the original message to each reply message. + + + + + + + + + + + + Indication whether the query was executed successfully or failed. + + + + + In case the query failed, this attribute must contain a human-readable description of the failure reason. + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/specifications/3.1.0/xsd/UFTP-cro-dso.xsd b/specifications/3.1.0/xsd/UFTP-cro-dso.xsd new file mode 100644 index 00000000..163fc510 --- /dev/null +++ b/specifications/3.1.0/xsd/UFTP-cro-dso.xsd @@ -0,0 +1,188 @@ + + + + + + + + + + + + + + + Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. + + + + + + + + + + + A congestion point that the DSO wants the CRO to update + + + + + + + EntityAddress of the Connection. + + + + + The first Period that the Connection is part of this CongestionPoint. + + + + + The last Period that the Connection is part of this CongestionPoint. + + + + + Indicates whether the DSO accepts mutual exclusive FlexOffers on this CongestionPoint. + + + + + Indicates which party is responsible for day-ahead redispatch. + + + + + Indicates which party is responsible for intraday ahead redispatch, AGR or DSO. If not specified, there will be no intraday trading on this CongestionPoint. + + + + + + + + + A connection that the DSO wants the CRO to update + + + + EntityAddress of the Connection. + + + + + The first Period that the Connection is part of this CongestionPoint. + + + + + The last Period that the Connection is part of this CongestionPoint. + + + + + + + + + + + + MessageID of the DSOPortfolioUpdateResponse that has just been accepted or rejected + + + + + + + + + + + + + + Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. + + + + + The Period for which the AGR requests the portfolio information. + + + + + EntityAddress of the CongestionPoint + + + + + + + + + + + + + + + + + MessageID of the AGRPortfolioQuery that has just been accepted or rejected + + + + + Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. + + + + + The Period for which the AGR requests the portfolio information. + + + + + + + + + + + + + + + EntityAddress of the Connection. + + + + + + + + + A Connection that is part of the congestion point. + + + + EntityAddress of the Connection. + + + + + The internet domain of the AGR that represents the prosumer connected on this Connection, if applicable. + + + + + + + + + + + diff --git a/specifications/3.1.0/xsd/UFTP-cro.xsd b/specifications/3.1.0/xsd/UFTP-cro.xsd new file mode 100644 index 00000000..6b706609 --- /dev/null +++ b/specifications/3.1.0/xsd/UFTP-cro.xsd @@ -0,0 +1,6 @@ + + + + + + diff --git a/specifications/3.1.0/xsd/UFTP-dso.xsd b/specifications/3.1.0/xsd/UFTP-dso.xsd new file mode 100644 index 00000000..3a86685f --- /dev/null +++ b/specifications/3.1.0/xsd/UFTP-dso.xsd @@ -0,0 +1,6 @@ + + + + + + diff --git a/specifications/3.1.0/xsd/UFTP-metering.xsd b/specifications/3.1.0/xsd/UFTP-metering.xsd new file mode 100644 index 00000000..3ba52e59 --- /dev/null +++ b/specifications/3.1.0/xsd/UFTP-metering.xsd @@ -0,0 +1,157 @@ + + + + + + + + + + + + + + + + + + + + + + kW must be used with Power profile values. + + + + + kWh must be used with energy profile values (ImportEnergy,ExportEnergy,ImportMeterReading,ExportMeterReading). + + + + + + + + + + + + The average active power during ISP, considering both import and export energy. Power=(ImportEnergy-ExportEnergy)*(60/ISP-Length-Minutes). + For example with a 15 minute ISP length we have a multiplier of 4, with a 30 minute ISP length we have a multiplier of 2. + Including the power profile is recommended. It is expected that in the following major version the power will become a mandatory value. + + + + + + Imported active energy, consumed during the ISP + + + + + Exported active energy, generated during the ISP + + + + + Cumulative metered imported active energy reading, at the end of the ISP + + + + + Cumulative metered exported active energy reading, at the end of the ISP + + + + + + + + + + + + + The message must contain one or more profiles with metering, energy or price values. + + + + + + Revision of this message. A sequence number that must be incremented each time a new revision of a metering message is sent. + + + + + ISO 8601 time interval (minutes only, for example PT15M) indicating the duration of the ISPs referenced in this message. Although the ISP length is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant ISP duration. + + + + + Time zone ID (as per the IANA time zone database, http://www.iana.org/time-zones, for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in each message is important for validation purposes, allowing implementations to reject messages with an errant UTC offset. + + + + + ISO 4217 code indicating the currency that applies to the price of the Tariff Rates. Only required if ImportTariff or ExportTariff profiles are included. + + + + + Day (in yyyy-mm-dd format) the ISPs referenced in this Metering message belong to. + + + + + EAN of the meter the message applies to. + + + + + + + + + + + A profile carries a sequence of ISPs with a defined type of metering data + + + + + + + + + + + + + + Number of the ISP this element refers to. The first ISP of a day has number 1. + + + + + Metering, energy or price value at the end of this ISP, in the designated profile units. + + + + + + + + + + + + MessageID of the Metering message this response is based on. + + + + + + + + + \ No newline at end of file diff --git a/specifications/development/README.md b/specifications/development/README.md new file mode 100644 index 00000000..4310b80f --- /dev/null +++ b/specifications/development/README.md @@ -0,0 +1,5 @@ +# Shapeshifter Specification Development + +This directory contains the mutable Markdown, image, and XSD sources for the draft following v3.1.0. The browsable draft is published by the `docs-latest` workflow. + +The sources are not a numbered release. Keep Markdown image references within `docs/` and XSD schema includes within `xsd/`. When a release is approved, create an immutable version snapshot from the release tag. \ No newline at end of file diff --git a/specifications/development/docs/about/levels-of-compliancy.md b/specifications/development/docs/about/levels-of-compliancy.md new file mode 100644 index 00000000..0d3ca92f --- /dev/null +++ b/specifications/development/docs/about/levels-of-compliancy.md @@ -0,0 +1,42 @@ + + +# Levels of compliancy + +UFTP has mandatory components and optional components. +The tables below list all core and optional components. +Support of core components is mandatory for all implementations. +Optional components are signaled throughout the document. +Optional components in messages are always prefixed with [optional]. + + +| Core UFTP components | USEF 2015 | UFTP | Signaled in CRO? | +| ------------------------------------ | :-------: | :----: | :--------------: | +| **UFTP process:** | | | | +| Day-ahead Flex trading | o | o | - | +| Redispatch responsibility choice | - | o | Y | +| Baseline choice | - | o | Y | +| **Market messages:** | | | | +| FlexRequest | o | o | - | +| FlexOffer | o | o | - | +| FlexOfferRevocation | o | o | - | +| FlexOrder | o | o | - | +| FlexSettlement | o | o | - | + +| Optional UFTP components | USEF 2015 | UFTP | Signaled in CRO? | +|--------------------------------------|:---------:|:------:|:----------------:| +| **UFTP Process:** | | | | +| Intraday Flex Trading | o | o | N | +| Availability contracts (FlexOptions) | ~[^1] | o | N | +| Dynamic pooling | - | future | ? | +| **Market messages:** | | | | +| D-prognosis | o | o | Y | +| FlexReservationUpdate | - | o | N | +| FlexOffer: mutual exclusive offers | - | o | Y | +| FlexOffer: unsolicited offers | - | o | - | +| FlexOffer: partial activation | - | o | - | + +[^1]: Availability contracts were mentioned in USEF2015, but not all details were worked out diff --git a/specifications/development/docs/about/purpose.md b/specifications/development/docs/about/purpose.md new file mode 100644 index 00000000..e65bf3fb --- /dev/null +++ b/specifications/development/docs/about/purpose.md @@ -0,0 +1,12 @@ + + +# Purpose + +The USEF Flex Trading protocol (UFTP) is a subset of the USEF framework. +Focused specifically on the exchange of flexibility between Aggregators (AGRs) and DSOs, it describes the corresponding market interactions between them to resolve grid constraints by applying congestion management or grid-capacity management. +UFTP can be used as a stand-alone protocol for flexibility forecasting, offering, ordering, and settlement processes. +Its purpose is to support the use of flexibility markets for grid-congestion issues and standardize the set-up and operation of these markets across different DSOs. diff --git a/specifications/development/docs/about/reading-guideline.md b/specifications/development/docs/about/reading-guideline.md new file mode 100644 index 00000000..c0529381 --- /dev/null +++ b/specifications/development/docs/about/reading-guideline.md @@ -0,0 +1,34 @@ + + +# Reading guideline + +The USEF Flexibility Trading Protocol Specification is accompanied by ‘USEF: The Framework explained’ [^B4] which provides insight into the background, scope and concepts underpinning USEF. +It is strongly advised that the USEF document is read in advance of this UFTP specification document. + +[^B4]: USEF Foundation, "USEF: The Framework Explained," USEF Foundation, Arnhem, 2015. + +USEF follows the principle of privacy & security by design and therefore the specifications are accompanied by a privacy & security guideline [^B5] which is applicable to the entire design, implementation and operation of USEF and derived products, services and solutions. + +[^B5]: USEF Foundation, "USEF: The Privacy and Security Guideline," USEF Foundation, Arnhem, 2015. Available: [https://www.usef.energy/app/uploads/2016/12/USEF_PrivacySecurityGuideline_3nov15.pdf](https://www.usef.energy/app/uploads/2016/12/USEF_PrivacySecurityGuideline_3nov15.pdf) + +The UFTP specifications consist of three main elements: + +- [General description](../general-description/index.md) +Informative description about usage of the protocol and process description for USEF’s market-based coordination mechanism + +- [Use case descriptions](../use-case-descriptions/scope.md) +Detailed descriptions of each process step of the process model, incl. scope & level, goal in context, preconditions, primary and secondary actors, the main scenario, etc. + +- [Message transport & descriptions](../message-descriptions/scope.md) +Syntax descriptions of all the messages required for the interfaces described in the framework, as well as detailed requirements for exchanging those messages. +A process description, including the specifications and rules that apply to each process, are provided. +A motivation for the design is included, wherever it is assumed beneficial. + +!!! success "Recommended Practice:" + + In order to make the universal descriptions of the framework applicable in practice and more comprehensible the specifications are accompanied by recommended practices. + These paragraphs are clearly indicated, in blue, throughout the specifications. diff --git a/specifications/development/docs/about/scope.md b/specifications/development/docs/about/scope.md new file mode 100644 index 00000000..5a9e98e4 --- /dev/null +++ b/specifications/development/docs/about/scope.md @@ -0,0 +1,68 @@ + + +# Scope + +## Constraint management services + +Constraint management services help grid operators (TSOs and DSOs) to optimize grid operation according to physical and market constraints. +USEF [^B1] distinguishes four different flexibility services within the constraint management category: grid capacity management, congestion management, voltage control and controlled islanding. +UFTP can be used for the first two of these. + +[^B1]: USEF, "Flexibility Value Chain (update 2018)," 8 10 2018. [Online]. Available: [https://www.usef.energy/app/uploads/2018/11/USEF-White-paper-Flexibility-Value-Chain-2018-version-1.0_Oct18.pdf](https://www.usef.energy/app/uploads/2018/11/USEF-White-paper-Flexibility-Value-Chain-2018-version-1.0_Oct18.pdf). + +### Grid capacity management + +Grid capacity management refers to the use of explicit demand-side flexibility (by the DSO or TSO) to increase operational efficiency without impacting freedom of dispatch, trade and connect (copper plate principle). +It is primarily used to defer grid reinforcements, optimize asset operational performance, reduce grid losses, or support planned maintenance. +The implication is that AGRs (and prosumers) participate in the product on a voluntary basis; i. +e. +motivated by appropriate financial incentives. + +### Congestion management + +Congestion management refers to the use of flexibility to reduce peak loads, in order to avoid system overload and the associated component or system failures. +Contrary to grid capacity management, it will typically limit freedom of dispatch, trade and/or connect. +It is primarily used in unanticipated overload situations; e. +g. +those which could not be forecast during long-term grid planning processes, or where load/ generation increases have outpaced grid reinforcement efforts. +Congestion management is a temporary solution (typically until grid reinforcement takes place) and is a highly-regulated mechanism. +At present, it is only available to TSOs in most European member states although it may be offered to DSOs in the future. + +The two mechanisms differ in the freedom of dispatch, trade and/or connect and this is handled via contracts and will have impact on the settlement components. + +## Bilateral trading and trading via a market platform + +![](../assets/images/image3.emf.odg.svg.png) + +UFTP is designed for bilateral trading between the AGR and DSO. +Trading via market platforms can bring added value, see [^B2]. +In UFTP, market platforms may take the role of trading counterparty, hence serving as a DSO proxy in trades with the AGR, and as an AGR proxy in trades with the DSO. +When trading via a platform, the role of FlexRequests from DSOs to AGRs is less obvious; i.e., a DSO has free choice of the available FlexOffers. +In addition, FlexOffers and FlexRequests do not need to be directly related and so UFTP supports unsolicited FlexOffers without requiring a reference to an underlying FlexRequest. + +## TSO/DSO coordination + +![](../assets/images/image4.emf.odg.svg.png) + +USEF assumes that a DSO or TSO can freely and independently trade flexibility with AGRs. +Any potential goal conflicts can be settled through the market mechanism. +Alternatively, TSO and DSO requests can be aligned, resulting in a TSO/DSO coordination platform where TSOs and DSOs coordinate the tendering, trading, activation and/or settlement of flexibility for their own purposes ( i. e. ancillary services). +See [^B2] for a discussion on this topic. + +[^B2]: USEF, "White paper: Flexibility Platforms," 2 november 2018. [Online]. Available: [https://www.usef.energy/app/uploads/2018/11/USEF-White-Paper-Flexibility-Platforms-version-1.0_Nov2018.pdf](https://www.usef.energy/app/uploads/2018/11/USEF-White-Paper-Flexibility-Platforms-version-1.0_Nov2018.pdf). + +UFTP can be applied without any further changes in a configuration where there is TSO/DSO coordination. + +## Alternative use + +The text, graphs and examples in this document assume flex trading between AGR and DSO. +However, UFTP can equally be used for grid constraint services between an AGR and TSO. + +The messages defined in UFTP can also be used for flexibility trading in the plan phase between an AGR and BRP. +See the USEF Framework Specifications [^B3] for a complete description of this alternative use. + +[^B3]: USEF, "USEF - The FrameWork Specifications 2015," 2015. [Online]. diff --git a/specifications/development/docs/appendix/bibliography.md b/specifications/development/docs/appendix/bibliography.md new file mode 100644 index 00000000..ca4af27b --- /dev/null +++ b/specifications/development/docs/appendix/bibliography.md @@ -0,0 +1,22 @@ + + +# Bibliography + +1. USEF, "Flexibility Value Chain (update 2018)," 8 10 2018. [Online]. Available: [https://www.usef.energy/app/uploads/2018/11/USEF-White-paper-Flexibility-Value-Chain-2018-version-1.0_Oct18.pdf](https://www.usef.energy/app/uploads/2018/11/USEF-White-paper-Flexibility-Value-Chain-2018-version-1.0_Oct18.pdf). +2. USEF, "White paper: Flexibility Platforms," 2 november 2018. [Online]. Available: [https://www.usef.energy/app/uploads/2018/11/USEF-White-Paper-Flexibility-Platforms-version-1.0_Nov2018.pdf](https://www.usef.energy/app/uploads/2018/11/USEF-White-Paper-Flexibility-Platforms-version-1.0_Nov2018.pdf). +3. USEF, "USEF - The FrameWork Specifications 2015," 2015. [Online]. +4. USEF Foundation, "USEF: The Framework Explained," USEF Foundation, Arnhem, 2015. +5. USEF Foundation, "USEF: The Privacy and Security Guideline," USEF Foundation, Arnhem, 2015. Available: [https://www.usef.energy/app/uploads/2016/12/USEF_PrivacySecurityGuideline_3nov15.pdf](https://www.usef.energy/app/uploads/2016/12/USEF_PrivacySecurityGuideline_3nov15.pdf) +6. USEF, "Recommended practices and key considerations for a regulatory framework and market design on explicit Demand Response," 2017. [Online]. Available: [https://www.usef.energy/app/uploads/2017/09/Recommended-practices-for-DR-market-design-2.pdf](https://www.usef.energy/app/uploads/2017/09/Recommended-practices-for-DR-market-design-2.pdf). +7. Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, ""Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616," 1999. +8. Bakke, M., Hafner, J., Hufferd, J., Voruganti, K., and M. Krueger, ""Internet Small Computer Systems Interface (iSCSI) Naming and Discovery", RFC 3721," 2004. +9. Satran, J., Meth, K., Sapuntzakis, C., Chadalapaka, M., and E. Zeidner, ""Internet Small Computer Systems Interface (iSCSI)", RFC 3720," 2004. +10. USEF Design Team, "Release Details USEF Specification 2014:I.I," USEF Foundation, Arnhem, 2014. +11. S. e. a. Tierney, "Pay-as-Bid vs. Uniform Pricing," Fortnightly Magazine, March 2008. +12. Wikipedia, "IEC 62056," 27 March 2014. [Online]. Available: [http://en.wikipedia.org/wiki/IEC_62056](http://en.wikipedia.org/wiki/IEC_62056). [Accessed 28 May 2014]. +13. P. v. Oirsouw, Netten voor distributie van electriciteit, Arnhem: Phase to Phase, 2012. +14. P. Mockapetris, ""Domain names - concepts and facilities", STD 13, RFC 1034," 1987. diff --git a/specifications/development/docs/appendix/flex-reservation-mechanism.md b/specifications/development/docs/appendix/flex-reservation-mechanism.md new file mode 100644 index 00000000..0ce3961e --- /dev/null +++ b/specifications/development/docs/appendix/flex-reservation-mechanism.md @@ -0,0 +1,44 @@ + + +# Flex reservation mechanism + +As introduced in [Bilateral contract: FlexOption](../general-description/contract-phase.md#bilateral-contract-flexoption), DSO’s may want to contract a minimum amount of flexibility to be sure that it is available on request. +The FlexOption (not part of UFTP) is a bilateral contract between DSO and AGR to reserve a specified amount of flexibility at a specific location (i.e. congestion point), for a specified time schedule and duration. +In the day-ahead grid planning process, the DSO’s forecast will indicate whether the contracted amount of flexibility is actually needed. +If not, the flexibility can be used for other purposes. +The DSO can send a FlexReservationUpdate message to signal the actual needs to the AGR. +This appendix describes the purpose of this FlexReservationUpdate message and its impact on the contractual obligations and the actual FlexRequest that may follow in the validate phase. + +
+ ![Example flex reservation and FlexReservationUpdate, displayed in graphs](../assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg.png){ width=1000px } +
Example flex reservation and FlexReservationUpdate, displayed in graphs
+
+ +The figure above illustrates how ISPs 11 to 16 are part of a contract, where the AGR is required to reserve flexibility at ISPs 12 to 15 (downwards power only – for more information on direction and amount of power, see Section [Power](../message-descriptions/message-catalog/power.md)). +The DSO was obliged to send a FlexReservationUpdate before each deadline, confirming the reserved power or partially releasing it. +The power values from the updated reservation should always be equal to, or lower than, the (absolute) values from the original reservation but since the contract is out-of-scope for UFTP, the DSO and AGR should maintain their own agreements about this. + +After the FlexReservationUpdate, the AGR is obliged to keep the amount of flexibility available – even if no FlexRequest follows. +After a FlexRequest is published, the AGR is obliged to produce a FlexOffer that meets the contract within the boundaries of the FlexRequest, where only the lowest reserved and requested power is valid for the contract. +This is illustrated in the following figure: + +
+ ![Example FlexRequest and requirements of FlexOffer, displayed in graphs](../assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg.png){ width=1000px } +
Example FlexRequest and requirements of FlexOffer, displayed in graphs
+
+ +For further information on the FlexRequest, see [Flexibility trading between the AGR and DSO](../general-description/validate-phase.md#flexibility-trading-between-the-agr-and-dso). +Both the FlexReservationUpdate and the FlexRequest can only reduce the amount of power that the AGR is obliged to offer, as opposed to increase it. +For ISP 12, the requested power exceeds the power that the AGR had to reserve in advance. +The contract is therefore only valid for the lowest (absolute) power value, being -2. +For ISP 14, the opposite is happening: the reserved power is not requested. +Therefore, the AGR is not obliged to provide flexibility for ISP 14. + +For ISP 15 and 16, available space is given for the AGR to deviate in the opposite direction. +**For all ISPs that are included in the contract – even when the reservation is set to 0 – the AGR is obliged to conform to the restrictions given by the FlexRequest, including the bounds of available space.** +The AGR is also free to provide more power than agreed, as long as it contributes to the decrease in congestion. +In this example, the resulting FlexOffer that complies to the contract must be as illustrated in the graph on the right in the figure above. diff --git a/specifications/development/docs/appendix/glossary.md b/specifications/development/docs/appendix/glossary.md new file mode 100644 index 00000000..b8639a05 --- /dev/null +++ b/specifications/development/docs/appendix/glossary.md @@ -0,0 +1,37 @@ + + +# Glossary + +| | | +|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------| +| A-plan | Aggregator-plan, used as Aggregator’s nomination | +| AGR | Aggregator. Role whose goal it is to maximize the value of flexibility, taking into account customer needs, economical optimization and grid capacity. | +| BRP | Balance Responsible Party | +| C&I | Commercial & Industry | +| Common Reference | Information about the Energy grid and the involved parties, which needs to be unambiguously available to all participating parties. | +| Congestion Point | Point in de grid where the grid capacity is not always sufficient to distribute the requested amount of energy | +| CRO | Common Reference Operator | +| D-prognosis | Prognosis regarding the Distribution of energy | +| DNO | Distribution Network Operator | +| DSO | Distribution System Operator | +| E-program | Energy Program – aggregated (daily) energy transactions of a BRP to be provided to the TSO | +| FlexOffer | Flexibility Offer, response to a Flexibility Request or unsolicited | +| FlexOrder | Flexibility Order, a response to a Flexibility Offer or direct | +| FlexRequest | Flexibility Request | +| Grid | Network for the transport and distribution of energy | +| ISP | Imbalance Settlement Period | +| MBMA | Measure Before Measure After (baseline methodology) | +| MCM | Market-based Coordination Mechanism (USEF) | +| MDC | Meter Data Company | +| P&S | Privacy & Security | +| Prosumer | A consumer which is capable of producing energy as well | +| Settlement | Determining the energy production and consumption and used flexibility as preparation for the billing process. | +| Supplier | Has a contractual relationship with Prosumers to source, supply and invoice energy | +| TSO | Transmission System Operator | +| UFTP | USEF Flex Trading Protocol | +| USEF | Universal Smart Energy Framework | + diff --git a/specifications/development/docs/appendix/message-transport-mechanism.md b/specifications/development/docs/appendix/message-transport-mechanism.md new file mode 100644 index 00000000..681a1bfb --- /dev/null +++ b/specifications/development/docs/appendix/message-transport-mechanism.md @@ -0,0 +1,248 @@ + + +# Message transport mechanism + +When implementing the USEF best-practice message transfer mechanism, the procedures outlined in this section apply. + +## Cryptographic Scheme (CS) + +The USEF privacy and security guidelines require all participants to be able to securely transmit and authenticate messages. +For these purposes, a transport-independent cryptographic scheme is specified, identified as Cryptographic Scheme Type 1 (CS1): implementation is a recommended practice for all implementations[^13]. +Based on NaCl[^14], a public domain library with high-speed state-of-the-art security features and a purpose-built and straightforward programming interface[^15], this scheme requires participants to generate two public/private key pairs: + +[^13]: If this recommendation is not followed, a compatible implementation should be provided in order to achieve USEF compliance. + +[^14]: + Pronounced “salt” and available with extensive documentation from [http://nacl.cr.yp.to/](http://nacl.cr.yp.to/). + Sodium, [https://github.com/jedisct1/libsodium](https://github.com/jedisct1/libsodium), is an extended NaCl derivative with Windows, OS X and Linux platform support and many available language bindings. + Sodium is highly recommended for USEF-compliant implementations. + +[^15]: Whereas typical cryptographic libraries require several steps to implement message encryption or signing, with each step opening the door for fatal programming mistakes, NaCl offers simple high-level functions which take care of everything, dramatically reducing the risk of inadvertent implementation errors. + +| Purpose | NaCl function | Private key bits | Public key bits | +|----------------------------------|---------------------|------------------|-----------------| +| Digital signatures | crypto_sign_keypair | 512 | 256 | +| Authenticated message encryption | crypto_box_keypair | 256 | 256 | + +The resulting private keys must be securely stored using an operating system or language-supplied facility for that specific purpose (e.g. the Win32 Data Protection API, OS X Keychain service or JVM KeyStore). +In addition to being stored locally, the public keys are exchanged with other USEF participants. +For that purpose, the keys are joined together in a single 64-byte array (signature key followed by encryption key), Base-64 encoded and prefixed by the constant cs1 and a period (indicating that the version 1 cryptographic scheme is used). +For example: `cs1.V4lZrkYHq8FzneXxUML+QEMXMul3tBm+gPGoVDIZBA92VoWTu8/kRu2Zx72XOm1i/qwwoSgXjqSAqSa43myCaQ==` + +This public key string can be published in the DNS zone of the domain used in the associated entity address, or manually exchanged with other USEF participants. +If DNS is used, implementation of DNSSEC is mandatory, as otherwise the key material would be completely untrusted. +Implementations must use a DNSSEC validating resolver, which can either be built-in, or an external resolver on a fully trusted network. + +When signing an outgoing message using the private digital signature key and NaCl’s `crypto_sign` function, the result is an opaque blob: the sealed message. +Unsealing this message, using the corresponding public digital signature key and `crypto_sign_open`, performs signature verification and returns the message plaintext. +Since this all happens in the same API call, it is not possible to accidentally process an unsigned or incorrectly signed message. + +### Message exchange logic + +The entire message exchange, from the client’s outgoing message queue to the server’s incoming message queue, using HTTP-over-TLS transport and the default cryptographic scheme, is visualized in detail in the picture below. + +
+ ![End-to-end USEF message exchange.](../assets/images/image23.emf.odg.svg.png){ width=1000px } +
End-to-end USEF message exchange.
+
+ +Messages go through the following stages between retrieval from the client’s outgoing message queue and delivery to the server’s inbound message queue. + +To prevent transient Internet connectivity or participant configuration issues from inhibiting message exchange, a retry mechanism could be implemented. The timer value used for such a period should be at least one hour for routine messages. +Note that, although message queue implementations may inform the sending process about delivery delays, only the final success or failure status is authoritative. +When retrying failed requests, the implementation must implement an exponential back off mechanism to prevent undue load on the remote service. + +## Service discovery + +### Versioning + +For versioning of the specification we use semantic versioning (see [https://semver.org/](https://semver.org/)). +In short: MAJOR.MINOR.PATCH. Each new major version is incompatible with previous versions; New minor versions are backwards compatible with previous minor versions within the same major version. + +### Supporting multiple versions of the protocol + +DSO’s should be more flexible than AGR’s, so DSO’s will support multiple versions of the protocol, but only for a restricted time. + +Also, the CRO should support multiple versions. + +DSO's and CRO are expected to support at most the three latest versions. + +### Version coupled to URL + +Each major version should have a different url-path, so it is possible to route each incompatible protocol version to another service. +This means that for minor changes and patches the url will remain the same. +The convention for the url-path (by example) is as follows: + +version 2.0.0: /shapeshifter/api/v2/message + +version 2.1.0: /shapeshifter/api/v2/message + +version 3.0.1: /shapeshifter/api/v3/message + +### Messages + +The metadata of each message contains the specification version. +A rejection reason will be added to reject a message with an invalid version + +### Service discovery + +The purpose of the discovery stage is to discover the endpoint, public-key for signing and, optionally, the capabilities (e.g. supported Shapeshifter versions) of the other participants. +The requirements for this stage rely heavily on agreements made between the participants that will be communicating with each other using the protocol. + +If service discovery fails due to inability to collect all required data within this timeout period, the delivery of the message fails. +Such messages are removed from the outgoing queue and returned to the sending process, indicating a transport error. + +#### Single authority + +One possible implementation for service discovery is creating a single authority that administers all the relevant information, and provides this to participants. +This approach could be seen as having a central address book, so all participants know where and how to send messages to each other. + +Activities on the energy market are most likely regulated by national oversight bodies. Such organizations are natural candidates for running such a service. Role-wise, this would be handled by the CRO, but in practice it might often be a DSO. + +#### DNS + +Another possible implementation for service discovery is DNS[^16]. +Assuming the Internet domain name of the remote participant is example.com, the relevant DNS records are as follows: + +[^16]: + Each USEF participant is responsible for publishing its own endpoint and public key information in a self-managed DNS zone. + To prevent man-in-the-middle interference with the published information, use of DNSSEC is mandatory for such zones. + +| | | +|----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| _usef.example.com | TXT record specifying the version of the USEF specification implemented by this participant, e.g. `2015` | +| \__role_._usef.example.com | TXT record containing up to two[^17] space-separated Base-64 encoded public key strings for the specified role, where role is one of the values `AGR`, `CRO` or `DSO`. This data is only queried if (part of) the outgoing message needs to be encrypted | +| _http.\_*role*._usef.example.com | CNAME record indicating the HTTP endpoint receiving messages for the specified role.
This label must not have any resource records of other types (with the exception of the mandatory DNSSEC-related records[^18]) and the alias should resolve to an A or AAAA record[^19].
On the endpoint host, the implementation must listen on the well-known IANA-assigned TCP port for HTTP-over-TLS, i.e. 443.
The implementation may listen on port 80 as well, but only for purposes such as supporting the HTTP/2 connection upgrade mechanism and never for unencrypted message exchange. | + +[^17]: Usually one public key string will be present, but in order to support key rotation without invalidating in-transit messages, the implementation should list both the old and the new key for a short period of time (e.g. 24 hours) after a key has been replaced + +[^18]: + USEF participants must enable DNSSEC and implementations must use a validating resolver, treating verification failures as temporary errors, eligible for retrying later. + Absent DNSSEC authentication, private key strings must not be relied on, and separate manual secure key exchange is required. + +[^19]: + As per IETF RFC 1034 [^B14], implementations must not fail when presented with CNAME chains or loops. + Chains should be followed (to an implementation-defined maximum depth) and any loops or errors treated as temporary. + +[^B14]: P. Mockapetris, ""Domain names - concepts and facilities", STD 13, RFC 1034," 1987. + +## Transmission + +Once a valid service endpoint is available, the message enters the transmission stage[^20]. +The implementation will now, for a reasonable amount of time (which is again at least one hour for routine messages, employing exponential back off), attempt to deliver the message to the remote participant. + +[^20]: For messages containing non-public information, this stage transition may also include encryption of message sections using the public encryption key of the remote participant. + +Messages are sent using a HTTP POST operation with the text/xml[^21] content type, the UTF8 character set and content-length indication. +The request URI depends on the USEF implementation level and host name listed in DNS by the recipient. +For USEF 2019 and the host `example.com`, it will be [https://example.com/USEF/2019/SignedMessage](https://example.com/USEF/2019/SignedMessage). + +[^21]: + The USEF specification uses XML, since this format is already widely used in the rather conservative energy market, and enjoys wide and mature tooling support (particularly in the area of schema authoring and validation). + Unlike other XML-based initiatives (such as WS-*), lightweight implementations are considered key, and alternate serialization formats (such as JSON) should be viable as well, despite being out of scope of this specification. + If any such alternate message formats are implemented, fallback to XML must be provided as needed, or such implementations will not be USEF-compliant. + +Message content consists of a simple wrapper message, specified as SignedMessage in the USEF XML XSD, available for download from the public USEF web site[^22] at [https://usef.info/schema/2019and](https://usef.info/schema/2019and) documented in section [Message catalog](../message-descriptions/message-catalog/index.md). +All usual protocol conventions should be followed during this stage. +For example, when using HTTP version 1.1, redirects (responses with status code 3xx) should be honored in order to support load balancing. +Any server errors (responses with status code 5xx), unknown response status codes, and connection timeouts and resets should be considered temporary failures and delivery should be re-attempted later within the timeout period. +Only client success or failure messages (responses with status code 200 or a non-ambiguous[^23] 4xx status code, respectively) should be considered final. +This is standard HTTP 1.1 behavior, as fully described in IETF RFC 2616 [^B7]. + +[^B7]: Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, ""Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616," 1999. + +[^22]: Please note that USEF makes no warranties whatsoever as to the uninterrupted availability of its web site, and that production services should not rely on the schema being hosted at this location for purposes such as validation: a local copy should be used instead. + +[^23]: The prime example of an ambiguous HTTP status code is 404 Not Found: since this is commonly returned by front-end servers in case of temporary back-end issues, USEF implementations are encouraged to consider this a temporary error.: + +## Error handling + +In the transmission stage, the guidelines for error handling are as follows: + +Until the point that the message has been successfully validated against the USEF XML schema, errors are communicated using transport protocol mechanisms, e.g. HTTP status codes. +For the HTTP protocol, the following error conditions are common (note that, depending on the server and libraries used, some of these may be handled automatically): + +| Condition | Status code | Error type | +|-----------------------------------------------------------------------------------------------------------------------|----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Missing Content-Length header | 411 Length Required | Permanent (E cannot be resolved without changes to the sending implementation) | +| Invalid Content-Type header (not text/xml) or character set (default: utf-8) | 400 Bad Request | Permanent | +| Originating IP address is sending messages at a rate exceeding receiver policy | 429 Too Many Requests | Temporary | +| Body XML cannot be parsed or is not compliant with USEF XML schema | 400 Bad Request | Permanent | +| Failed to look up the sender’s public signature key in DNS | 419 Authentication Timeout | Temporary (message can be processed when DNS is corrected/replicated) | +| Invalid signature (inner XML message cannot be unsealed, for example due to NaCl’s crypto_sign_open function failing) | 401 Unauthorized | Permanent (since no authorization schemes that would allow the request to be resubmitted are available, unless private arrangements between sender and recipient exist) | +| Unsealed body XML cannot be parsed or is not compliant with the USEF XML schema | 400 Bad Request | Permanent | + +Once a message has been determined to be valid USEF XML, errors are reported using a USEF XML response message with a successful transport disposition (e.g. HTTP status code 200 OK). Possible results in this stage are: + +As in the service discovery stage, messages for which transmission permanently fails are removed from the outgoing queue and returned to the sending process, indicating a transport error. + +### Common Message Metadata + +The USEF XML message obtained after successfully verifying the signature will have a root node corresponding to its message type, which must contain Metadata attributes common to all messages used by the implementation to process the message. +The metadata attributes are defined in [metadata attributes](../message-descriptions/message-catalog/metadata-attributes.md). + +## Awaiting reply + +If message transmission succeeds, the implementation starts waiting for a reply from the remote service. +Although replies to some messages can be expected immediately, other USEF messages may only elicit a response several hours later. +In any case, responses are always decoupled from requests and implementations should be strictly asynchronous, correlating requests and responses using their conversation identifier. + +Because of the asynchronous nature of message exchange, a process needs to be in place for handling messages that do not receive a (timely) reply. +When preparing a new message, the implementation should specify the message class, as well as the time period within which a reply is expected. +The following message classes are defined: + +Incoming replies are validated using the steps outlined in the transmission stage. +Where a reply is rejected, the pending outgoing message remains in the awaiting reply stage until it expires, and any additional manual processing is completed. +Messages for which, ultimately, no reply is received are returned to the sending process, indicating expiry. + +## Service process message error handling + +Since the message exchange process is responsible for transparently handling most, if not all, transient error conditions, service processes have no need for routine error recovery. +In fact, any transport errors reported to the service layer are of such a severe nature that they most likely cannot be corrected without implementation or configuration changes: + +- Malformed messages +- Entity address or signing key misconfigurationsExpired message, despite following manual recovery procedures for non-routine messages (for routine messages, no recovery is required by design but logging may definitely be appropriate) + +The suggested error handling strategy for service processes is to mark the affected remote participant (i.e. not try to exchange any future messages with it) and to emit a diagnostic message indicating that manual intervention is required. +After the issue is investigated and resolved, the configuration can be manually updated to re-enable the participant. + +## EA1 addressing scheme + +In USEF messages, there is often a requirement for a globally unique identity for certain entities. +To meet this requirement, USEF defines the Entity Address (EA). +Each EA consists of a prefix, indicating the addressing scheme, followed by the actual address. +Currently, two addressing schemes are supported: + +- The European Article Number (EAN), commonly used to uniquely identify connection points in the electricity network and therefore a natural identifier to do the same in USEF. +An example of an EA using this scheme is: ean.871685900012636543 +- The USEF type 1 entity address (EA1) is designed to allow participants to generate unique identifiers for themselves and entities managed by them, without relying on a central authority. + +The USEF type 1 EA is structured analogous to the iSCSI IQN. +Paraphrasing IETF RFCs 3720 and 3271 [^B8]: the EA does not define any new naming authorities but uses Internet domain names to ensure global uniqueness. +Furthermore, the EA is constructed to give an organizational naming authority the flexibility to further subdivide the responsibility for name creation to subordinate naming authorities. + +[^B8]: Bakke, M., Hafner, J., Hufferd, J., Voruganti, K., and M. Krueger, ""Internet Small Computer Systems Interface (iSCSI) Naming and Discovery", RFC 3721," 2004. + +This makes the EA format slightly unwieldy but since bandwidth and storage space are not expected to be significant constraints in any USEF implementation, this is considered to be an acceptable tradeoff for not requiring a central authority. +Syntactically, an EA is a variable-length, 7-bit printable ASCII text string containing up to 255 characters. +For example: + +``` +ea1.2013-11.info.usef.test:001:002.090807002a&b# + <- naming authority -> < unique identifier > +``` + +Mostly taken from IETF RFC 3720 [^B9], below are the semantics of the various parts of this EA: + +[^B9]: Satran, J., Meth, K., Sapuntzakis, C., Chadalapaka, M., and E. Zeidner, ""Internet Small Computer Systems Interface (iSCSI)", RFC 3720," 2004. + +| | | +|---------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **ea1** | Constant, indicating this is a type 1 USEF entity address | +| **2013-11** | A date code, in yyyy-mm format. This date must be a date during which the naming authority owned the domain name used in this format, and should be the first month in which the domain name was owned by this naming authority at 00:01 GMT of the first day of the month. This date code uses the Gregorian calendar. All four digits in the year must be present. Both digits of the month must be present, with January == "01" and December == "12". The dash must be included. | +| **info.usef.test** | The reversed domain name of the naming authority (person or organization) creating this entity address | +| **001:002.090807002a&b#** | A locally unique string, which may contain product types, serial numbers, host identifiers, or software keys (specifically: it may include colons to separate organization boundaries). With the exception of the colon prefix, the owner of the domain name can assign everything after the reversed domain name as desired. It is the responsibility of the entity that is the naming authority to ensure that the names it assigns are worldwide unique. | diff --git a/specifications/development/docs/appendix/rationale-for-information-exchange-in-flexibility-request.md b/specifications/development/docs/appendix/rationale-for-information-exchange-in-flexibility-request.md new file mode 100644 index 00000000..29c0b90d --- /dev/null +++ b/specifications/development/docs/appendix/rationale-for-information-exchange-in-flexibility-request.md @@ -0,0 +1,29 @@ + + +# Rationale for information exchange in flexibility request + +USEF specifies that when sending a flexibility request, the DSO provides the following information about expected congestion. This appendix provides the rationale. + +- **Information about expected congestion is provided to all registered AGRs:** +The reduction required must be made available to all AGRs operating in the specific congestion area, due to the DSO’s legal obligation to treat all market parties in a non-discriminatory way. +The grid topology, however, is considered to be confidential information. +Therefore, USEF recommends that information about expected congestion is not provided freely to the entire market at national level. + +- **Information about expected congestion includes the direction of the overload (production/consumption):** +A grid overload at a congestion point can occur as a result of either too much production or too much consumption. +To reduce overload where there is too much production, either the production must be reduced, or the consumption must be increased. +For overload where there is too much consumption, this is the other way around (increase production or decrease consumption). +The implication is that the congestion information provided must be clear about the direction of the overload. + +- **Information about expected congestion includes the volume of reduction required.** +While it is sufficient for the DSO to provide only information about the need for reduction, rather than the volume of reduction required for an ISP, it makes sense to provide more detailed information as this is likely to result in a more optimal use of flexibility and therefore better usage of the grid. + +- **Information about expected congestion includes available grid capacity for other ISPs.** +Providing insight on the available grid capacity for the ISPs without congestion gives AGRs additional information that can be used to determine their flexibility offers. +In addition, it reduces the likelihood that the load shift provided by the AGRs will create a new peak that overloads the grid, and thus is likely to converge quicker, making the time needed to align a D-prognosis shorter. +Whether or not this time is needed mainly depends on the number of congestion points a DSO has defined. +On the downside, the more information provided by the DSO, the easier it is to get insight into the entire grid topology, especially for crucial points in the grid. diff --git a/specifications/development/docs/assets/images/README.md b/specifications/development/docs/assets/images/README.md new file mode 100644 index 00000000..cb4fc280 --- /dev/null +++ b/specifications/development/docs/assets/images/README.md @@ -0,0 +1,25 @@ + + +# Images + +This folder contains images used in the documentation. + +## EMF files + +Many images originate from the original USEF specification created in Microsoft Word. +During the migration to Markdown based documentation these images have been exported to EMF (Enhanced Windows Metafile) files. +To convert these images to open standards, they have been opened in LibreOffice Draw and saved as ODG files, as well as being exported to SVG files. +Although SVG files work well for the web-based documentation, some show up with wrong fonts and black elements in the PDF export. +Therefore the SVG files have been exported to rendered PNG files for final use. + +### Rendering PNG files + +The PNG files have been generated from the SVG files using Inkscape on the Bash commandline: + +``` +# for IMG in $(ls *.svg); do inkscape ${IMG} -o ${IMG}.png --export-dpi=150; done +``` diff --git a/specifications/development/docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg b/specifications/development/docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg new file mode 100644 index 00000000..3190e973 --- /dev/null +++ b/specifications/development/docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg @@ -0,0 +1,3023 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -6 + + + + + -4 + + + + + -2 + + + + + 0 + + + + + 2 + + + + + 4 + + + + + 11 + + + + + 12 + + + + + 13 + + + + + 14 + + + + + 15 + + + + + 16 + + + + + FlexRequest + + + + + + Requested power exceeds + + + + + contracted power + + + + + + + + + + Requested power smaller than + + + + + contracted power + + + + + + + + Available + + + + + space: valid for + + + + + contract + + + + + + + + + + + + + + + + + + + + + + + -6 + + + + + -4 + + + + + -2 + + + + + 0 + + + + + 2 + + + + + 4 + + + + + 11 + + + + + 12 + + + + + 13 + + + + + 14 + + + + + 15 + + + + + 16 + + + + + Compliant FlexOffer + + + + + + Obligated + + + + + + + + + Free space + + + + + + + + diff --git a/specifications/development/docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg.license b/specifications/development/docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg.png b/specifications/development/docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg.png new file mode 100644 index 00000000..4696f5ab Binary files /dev/null and b/specifications/development/docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg.png differ diff --git a/specifications/development/docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg.png.license b/specifications/development/docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg.png.license new file mode 100644 index 00000000..49cbec7e --- /dev/null +++ b/specifications/development/docs/assets/images/appendix-flex-reservation-mechanism-flex-request-flexoffer.svg.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg b/specifications/development/docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg new file mode 100644 index 00000000..ef507f0e --- /dev/null +++ b/specifications/development/docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg @@ -0,0 +1,2878 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -6 + + + + + -4 + + + + + -2 + + + + + 0 + + + + + 2 + + + + + 4 + + + + + 11 + + + + + 12 + + + + + 13 + + + + + 14 + + + + + 15 + + + + + 16 + + + + + Contracted flex reservation + + + + + + + + + -6 + + + + + -4 + + + + + -2 + + + + + 0 + + + + + 2 + + + + + 4 + + + + + 11 + + + + + 12 + + + + + 13 + + + + + 14 + + + + + 15 + + + + + 16 + + + + + FlexReservationUpdate + + + + + + Reservation is set + + + + + + + + + Reservation is decreased + + + + + + + + + Reservation is released + + + + + + + + + + + + + + + + + + + + + + + diff --git a/specifications/development/docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg.license b/specifications/development/docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg.png b/specifications/development/docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg.png new file mode 100644 index 00000000..c74a587b Binary files /dev/null and b/specifications/development/docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg.png differ diff --git a/specifications/development/docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg.png.license b/specifications/development/docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg.png.license new file mode 100644 index 00000000..49cbec7e --- /dev/null +++ b/specifications/development/docs/assets/images/appendix-flex-reservation-mechanism-flex-reservation-flex-reservation-update.svg.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image1.png b/specifications/development/docs/assets/images/image1.png new file mode 100644 index 00000000..d8621621 Binary files /dev/null and b/specifications/development/docs/assets/images/image1.png differ diff --git a/specifications/development/docs/assets/images/image1.png.license b/specifications/development/docs/assets/images/image1.png.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image1.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image13.emf b/specifications/development/docs/assets/images/image13.emf new file mode 100644 index 00000000..a252595d Binary files /dev/null and b/specifications/development/docs/assets/images/image13.emf differ diff --git a/specifications/development/docs/assets/images/image13.emf.license b/specifications/development/docs/assets/images/image13.emf.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image13.emf.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image13.emf.odg b/specifications/development/docs/assets/images/image13.emf.odg new file mode 100644 index 00000000..bd7ca460 Binary files /dev/null and b/specifications/development/docs/assets/images/image13.emf.odg differ diff --git a/specifications/development/docs/assets/images/image13.emf.odg.license b/specifications/development/docs/assets/images/image13.emf.odg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image13.emf.odg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image13.svg b/specifications/development/docs/assets/images/image13.svg new file mode 100644 index 00000000..261cdf24 --- /dev/null +++ b/specifications/development/docs/assets/images/image13.svg @@ -0,0 +1,3835 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0 + + + + + 1 + + + + + 0 + + + + + 2 + + + + + 0 + + + + + 3 + + + + + 0 + + + + + 1 + + + + + 2 + + + + + 3 + + + + + 4 + + + + + 5 + + + + + F + + + + + o + + + + + r + + + + + e + + + + + c + + + + + a + + + + + s + + + + + t + + + + + + + + + + + - + + + + + 5 + + + + + 0 + + + + + - + + + + + 3 + + + + + 0 + + + + + - + + + + + 1 + + + + + 0 + + + + + 1 + + + + + 0 + + + + + 1 + + + + + 2 + + + + + 3 + + + + + 4 + + + + + 5 + + + + + F + + + + + l + + + + + e + + + + + x + + + + + R + + + + + e + + + + + q + + + + + u + + + + + e + + + + + s + + + + + t + + + M + a + x + P + o + w + e + r + + M + i + n + P + o + w + e + r + + D + i + s + p + o + s + i + t + i + o + n + = + “ + R + e + q + u + e + s + t + e + d + ” + + D + i + s + p + o + s + i + t + i + o + n + = + “ + A + v + a + i + l + a + b + l + e + ” + + + + + + + + + diff --git a/specifications/development/docs/assets/images/image13.svg.license b/specifications/development/docs/assets/images/image13.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image13.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image13.svg.png b/specifications/development/docs/assets/images/image13.svg.png new file mode 100644 index 00000000..fff72beb Binary files /dev/null and b/specifications/development/docs/assets/images/image13.svg.png differ diff --git a/specifications/development/docs/assets/images/image13.svg.png.license b/specifications/development/docs/assets/images/image13.svg.png.license new file mode 100644 index 00000000..49cbec7e --- /dev/null +++ b/specifications/development/docs/assets/images/image13.svg.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image14.emf b/specifications/development/docs/assets/images/image14.emf new file mode 100644 index 00000000..4976cc21 Binary files /dev/null and b/specifications/development/docs/assets/images/image14.emf differ diff --git a/specifications/development/docs/assets/images/image14.emf.license b/specifications/development/docs/assets/images/image14.emf.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image14.emf.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image14.emf.odg b/specifications/development/docs/assets/images/image14.emf.odg new file mode 100644 index 00000000..506cf33d Binary files /dev/null and b/specifications/development/docs/assets/images/image14.emf.odg differ diff --git a/specifications/development/docs/assets/images/image14.emf.odg.license b/specifications/development/docs/assets/images/image14.emf.odg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image14.emf.odg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image14.emf.odg.svg b/specifications/development/docs/assets/images/image14.emf.odg.svg new file mode 100644 index 00000000..41d2d45e --- /dev/null +++ b/specifications/development/docs/assets/images/image14.emf.odg.svg @@ -0,0 +1,250 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + day + - + 1 + + + + + + + + + + + + day + of delivery + + + + + + + + + + + time + window + day + - + ahead + trading + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + USEF + day + - + ahead + gate + closure + national + balacing + regime + gate + closure + + + + + + + + + + + + + + + 2h + + + + + + + + + \ No newline at end of file diff --git a/specifications/development/docs/assets/images/image14.emf.odg.svg.license b/specifications/development/docs/assets/images/image14.emf.odg.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image14.emf.odg.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image14.emf.odg.svg.png b/specifications/development/docs/assets/images/image14.emf.odg.svg.png new file mode 100644 index 00000000..571f7504 Binary files /dev/null and b/specifications/development/docs/assets/images/image14.emf.odg.svg.png differ diff --git a/specifications/development/docs/assets/images/image14.emf.odg.svg.png.license b/specifications/development/docs/assets/images/image14.emf.odg.svg.png.license new file mode 100644 index 00000000..49cbec7e --- /dev/null +++ b/specifications/development/docs/assets/images/image14.emf.odg.svg.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image15.emf b/specifications/development/docs/assets/images/image15.emf new file mode 100644 index 00000000..7dfae79e Binary files /dev/null and b/specifications/development/docs/assets/images/image15.emf differ diff --git a/specifications/development/docs/assets/images/image15.emf.license b/specifications/development/docs/assets/images/image15.emf.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image15.emf.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image15.emf.odg b/specifications/development/docs/assets/images/image15.emf.odg new file mode 100644 index 00000000..9af2a1c1 Binary files /dev/null and b/specifications/development/docs/assets/images/image15.emf.odg differ diff --git a/specifications/development/docs/assets/images/image15.emf.odg.license b/specifications/development/docs/assets/images/image15.emf.odg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image15.emf.odg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image15.emf.odg.svg b/specifications/development/docs/assets/images/image15.emf.odg.svg new file mode 100644 index 00000000..451b563b --- /dev/null +++ b/specifications/development/docs/assets/images/image15.emf.odg.svg @@ -0,0 +1,525 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + current + time 11:00 + pm + , gate + closure + for + ISP 1 + + + + + + + + + + + + + + ISP 5..94 + + + + + + + + + + + ISPs + 1..96 open + for + intraday + trading + + + + + + + + + + + + + 1h + + + + + + + + + + + 1 + + + + + + + + + + + 2 + + + + + + + + + + + 3 + + + + + + + + + + + 4 + + + + + + + + + + + 95 + + + + + + + + + + + 96 + + + + + + + + + + + + + + + + + ISPs + 3..96 open + for + intraday + trading + ISPs + 95..96 open + for + intraday + trading + + + + + + + + + + + + ISP 5..94 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + current time 11:30 + pm + , gate + closure + for + ISP 3 + + + + + + + + + + + + + 1h + + + + + + + + + + + + + 3 + + + + + + + + + + + 4 + + + + + + + + + + + 95 + + + + + + + + + + + 96 + + + + + + + + + + + + + + + + + + + + + ISP 5..94 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + current time 10:30 + pm + , gate + closure + for + ISP 95 + + + + + + + + + + + + + 1h + + + + + + + + + + + + + 3 + + + + + + + + + + + 4 + + + + + + + + + + + 95 + + + + + + + + + + + 96 + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/specifications/development/docs/assets/images/image15.emf.odg.svg.license b/specifications/development/docs/assets/images/image15.emf.odg.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image15.emf.odg.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image15.emf.odg.svg.png b/specifications/development/docs/assets/images/image15.emf.odg.svg.png new file mode 100644 index 00000000..7387fa54 Binary files /dev/null and b/specifications/development/docs/assets/images/image15.emf.odg.svg.png differ diff --git a/specifications/development/docs/assets/images/image15.emf.odg.svg.png.license b/specifications/development/docs/assets/images/image15.emf.odg.svg.png.license new file mode 100644 index 00000000..49cbec7e --- /dev/null +++ b/specifications/development/docs/assets/images/image15.emf.odg.svg.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image18.emf b/specifications/development/docs/assets/images/image18.emf new file mode 100644 index 00000000..bfa25563 Binary files /dev/null and b/specifications/development/docs/assets/images/image18.emf differ diff --git a/specifications/development/docs/assets/images/image18.emf.license b/specifications/development/docs/assets/images/image18.emf.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image18.emf.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image18.emf.odg b/specifications/development/docs/assets/images/image18.emf.odg new file mode 100644 index 00000000..8d63146f Binary files /dev/null and b/specifications/development/docs/assets/images/image18.emf.odg differ diff --git a/specifications/development/docs/assets/images/image18.emf.odg.license b/specifications/development/docs/assets/images/image18.emf.odg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image18.emf.odg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image18.emf.odg.svg b/specifications/development/docs/assets/images/image18.emf.odg.svg new file mode 100644 index 00000000..3989dd35 --- /dev/null +++ b/specifications/development/docs/assets/images/image18.emf.odg.svg @@ -0,0 +1,350 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Role + process + messages + (USEF + core + ) + + + + + + + + + + + Message transfer mechanism + (USEF + recommended + practice + ) + + + + + + + + + + + DNSSEC + + + + + + + + + + + SignedMessage + XM + L + + + + + + + + + + + Allow/deny lists + + + + + + + + + + + NaCl elliptic curve + encryption + + + + + + + + + + + Service discovery + + + + + + + + + + + HTTP+SSL + + + + + + + + + + + Recipient: Internet domain, USEF role + + + + + + + + + + + XML content as per + https://usef.energy/schema/2019/messaging.xsd + + + + + + + + + + + Authenticatio + n + + + + + + + + + + + Abuse + mitigation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Remove + USEF + participant + s + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/specifications/development/docs/assets/images/image18.emf.odg.svg.license b/specifications/development/docs/assets/images/image18.emf.odg.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image18.emf.odg.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image18.emf.odg.svg.png b/specifications/development/docs/assets/images/image18.emf.odg.svg.png new file mode 100644 index 00000000..606f3b8c Binary files /dev/null and b/specifications/development/docs/assets/images/image18.emf.odg.svg.png differ diff --git a/specifications/development/docs/assets/images/image18.emf.odg.svg.png.license b/specifications/development/docs/assets/images/image18.emf.odg.svg.png.license new file mode 100644 index 00000000..49cbec7e --- /dev/null +++ b/specifications/development/docs/assets/images/image18.emf.odg.svg.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image19.png b/specifications/development/docs/assets/images/image19.png new file mode 100644 index 00000000..9f69e99a Binary files /dev/null and b/specifications/development/docs/assets/images/image19.png differ diff --git a/specifications/development/docs/assets/images/image19.png.license b/specifications/development/docs/assets/images/image19.png.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image19.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image2.png b/specifications/development/docs/assets/images/image2.png new file mode 100644 index 00000000..4e2d1d40 Binary files /dev/null and b/specifications/development/docs/assets/images/image2.png differ diff --git a/specifications/development/docs/assets/images/image2.png.license b/specifications/development/docs/assets/images/image2.png.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image2.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image20.png b/specifications/development/docs/assets/images/image20.png new file mode 100644 index 00000000..3b8ffd45 Binary files /dev/null and b/specifications/development/docs/assets/images/image20.png differ diff --git a/specifications/development/docs/assets/images/image20.png.license b/specifications/development/docs/assets/images/image20.png.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image20.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image21.png b/specifications/development/docs/assets/images/image21.png new file mode 100644 index 00000000..808befa1 Binary files /dev/null and b/specifications/development/docs/assets/images/image21.png differ diff --git a/specifications/development/docs/assets/images/image21.png.license b/specifications/development/docs/assets/images/image21.png.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image21.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image22.png b/specifications/development/docs/assets/images/image22.png new file mode 100644 index 00000000..cf1641fd Binary files /dev/null and b/specifications/development/docs/assets/images/image22.png differ diff --git a/specifications/development/docs/assets/images/image22.png.license b/specifications/development/docs/assets/images/image22.png.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image22.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image23.emf b/specifications/development/docs/assets/images/image23.emf new file mode 100644 index 00000000..9412d98b Binary files /dev/null and b/specifications/development/docs/assets/images/image23.emf differ diff --git a/specifications/development/docs/assets/images/image23.emf.license b/specifications/development/docs/assets/images/image23.emf.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image23.emf.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image23.emf.odg b/specifications/development/docs/assets/images/image23.emf.odg new file mode 100644 index 00000000..ced3431f Binary files /dev/null and b/specifications/development/docs/assets/images/image23.emf.odg differ diff --git a/specifications/development/docs/assets/images/image23.emf.odg.license b/specifications/development/docs/assets/images/image23.emf.odg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image23.emf.odg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image23.emf.odg.svg b/specifications/development/docs/assets/images/image23.emf.odg.svg new file mode 100644 index 00000000..51da9bc2 --- /dev/null +++ b/specifications/development/docs/assets/images/image23.emf.odg.svg @@ -0,0 +1,613 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Client + + + + + + + + + + + Server + + + + + + + + + + + 1. retrieve message from outbound queue + + + + + + + + + + + 2. determine USEF endpoint of recipient + + + + + + + + + + + 3. sign UTF + - + 8 representation using NaCl and + compose message to be transmitted + + + + + + + + + + + USEF XML message + + + + + + + + + + + DNS/configuration + + + + + + + + + + + private signing key + + + + + + + + + + + USEF XML SignedMessage: + - + Sender DNS Domain + - + Sender role + - + Base64 encoded NaCl sealed message + + + + + + + + + + + 4. post text/xml body over HTTPS + + + + + + + + + + + 5. check HTTP result code: + a. + Temporary + error? + b. + Permanent + error? + c. + Success? + + + + + + + + + + + 6. check XML result attribute: + d. + Rejected? + e. + Success? + + + + + + + + + + + + + + + + + + + + + + + + + + 7. update message status in outbound queue + a + . + Retry + later + * + b/d + Delivery + failed + e. + Waiting for reply + ( + * + unless message has expired then use scenario b) + + + + + + + + + + + + case c + case a/b + + + + + + + + + + + + + + + 1. check HTTP protocol requirements + + + + + + + + + + + 3. obtain public signing key; + unseal NaCl message + + + + + + + + + + + USEF XML schema + + + + + + + + + + + connection history + + + + + + + + + + + 4. validate received message + + + + + + + + + + + + + + + + + + + + + + + + + 5. store message in inbound message queue + + + + + + + + + + + + HTTP 200 OK + + + + + + + + + + + + + 2. parse XML SignedMessage + + + + + + + + + + + DNS/configuration + + + + + + + + + + + USEF XML message + + + + + + + + + + + configuration + + + + + + + + + + + + + F + + + + + + + + + + + F + + + + + + + + + + + F + + + + + + + + + + + F + + + + + + + + + + + + + + + + + F + + + + + + + + + + + + + + HTTP ERROR + (e.g. 400 Bad Request) + OK + + + + + + + + + + + + OK + Failure + OK + Failure + OK + Failure + Rejected + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/specifications/development/docs/assets/images/image23.emf.odg.svg.license b/specifications/development/docs/assets/images/image23.emf.odg.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image23.emf.odg.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image23.emf.odg.svg.png b/specifications/development/docs/assets/images/image23.emf.odg.svg.png new file mode 100644 index 00000000..3e12e82d Binary files /dev/null and b/specifications/development/docs/assets/images/image23.emf.odg.svg.png differ diff --git a/specifications/development/docs/assets/images/image23.emf.odg.svg.png.license b/specifications/development/docs/assets/images/image23.emf.odg.svg.png.license new file mode 100644 index 00000000..49cbec7e --- /dev/null +++ b/specifications/development/docs/assets/images/image23.emf.odg.svg.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image24.emf b/specifications/development/docs/assets/images/image24.emf new file mode 100644 index 00000000..f0481477 Binary files /dev/null and b/specifications/development/docs/assets/images/image24.emf differ diff --git a/specifications/development/docs/assets/images/image24.emf.license b/specifications/development/docs/assets/images/image24.emf.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image24.emf.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image24.emf.odg b/specifications/development/docs/assets/images/image24.emf.odg new file mode 100644 index 00000000..5f8b51ac Binary files /dev/null and b/specifications/development/docs/assets/images/image24.emf.odg differ diff --git a/specifications/development/docs/assets/images/image24.emf.odg.license b/specifications/development/docs/assets/images/image24.emf.odg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image24.emf.odg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image24.emf.odg.svg b/specifications/development/docs/assets/images/image24.emf.odg.svg new file mode 100644 index 00000000..21fccbe8 --- /dev/null +++ b/specifications/development/docs/assets/images/image24.emf.odg.svg @@ -0,0 +1,76 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/specifications/development/docs/assets/images/image24.emf.odg.svg.license b/specifications/development/docs/assets/images/image24.emf.odg.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image24.emf.odg.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image24.emf.odg.svg.png b/specifications/development/docs/assets/images/image24.emf.odg.svg.png new file mode 100644 index 00000000..6a67c9b4 Binary files /dev/null and b/specifications/development/docs/assets/images/image24.emf.odg.svg.png differ diff --git a/specifications/development/docs/assets/images/image24.emf.odg.svg.png.license b/specifications/development/docs/assets/images/image24.emf.odg.svg.png.license new file mode 100644 index 00000000..49cbec7e --- /dev/null +++ b/specifications/development/docs/assets/images/image24.emf.odg.svg.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image24.svg b/specifications/development/docs/assets/images/image24.svg new file mode 100644 index 00000000..24e3a69e --- /dev/null +++ b/specifications/development/docs/assets/images/image24.svg @@ -0,0 +1,2495 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + D + S + O + . + e + x + a + m + p + l + e + D + N + S + + + _ + U + S + E + F + + + _ + D + S + O + + + _ + C + R + O + + + T + X + T + + + C + N + A + M + E + + + T + X + T + + + C + N + A + M + E + + + A + / + A + A + A + A + + + + + D + S + O + - + a + f + f + i + l + i + a + t + e + d + - + A + g + g + r + e + g + a + t + o + r + - + 1 + . + e + x + a + m + p + l + e + D + N + S + + + T + X + T + + + C + N + A + M + E + + + _ + A + G + R + + + _ + U + S + E + F + + + + T + i + n + y + - + A + g + g + r + e + g + a + t + o + r + . + e + x + a + m + p + l + e + D + N + S + + + T + X + T + + + C + N + A + M + E + + + _ + U + S + E + F + + + _ + A + G + R + + + + + + + + S + S + L + + + + + + + diff --git a/specifications/development/docs/assets/images/image24.svg.license b/specifications/development/docs/assets/images/image24.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image24.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image24.svg.png b/specifications/development/docs/assets/images/image24.svg.png new file mode 100644 index 00000000..75874afc Binary files /dev/null and b/specifications/development/docs/assets/images/image24.svg.png differ diff --git a/specifications/development/docs/assets/images/image24.svg.png.license b/specifications/development/docs/assets/images/image24.svg.png.license new file mode 100644 index 00000000..49cbec7e --- /dev/null +++ b/specifications/development/docs/assets/images/image24.svg.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image25.png b/specifications/development/docs/assets/images/image25.png new file mode 100644 index 00000000..d17f652f Binary files /dev/null and b/specifications/development/docs/assets/images/image25.png differ diff --git a/specifications/development/docs/assets/images/image25.png.license b/specifications/development/docs/assets/images/image25.png.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image25.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image3.emf b/specifications/development/docs/assets/images/image3.emf new file mode 100644 index 00000000..57cc04e4 Binary files /dev/null and b/specifications/development/docs/assets/images/image3.emf differ diff --git a/specifications/development/docs/assets/images/image3.emf.license b/specifications/development/docs/assets/images/image3.emf.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image3.emf.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image3.emf.odg b/specifications/development/docs/assets/images/image3.emf.odg new file mode 100644 index 00000000..b8824ece Binary files /dev/null and b/specifications/development/docs/assets/images/image3.emf.odg differ diff --git a/specifications/development/docs/assets/images/image3.emf.odg.license b/specifications/development/docs/assets/images/image3.emf.odg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image3.emf.odg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image3.emf.odg.svg b/specifications/development/docs/assets/images/image3.emf.odg.svg new file mode 100644 index 00000000..02cb08bb --- /dev/null +++ b/specifications/development/docs/assets/images/image3.emf.odg.svg @@ -0,0 +1,240 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + AGR + + + + + + + + + + + + + + + + DSO + + + + + + + + + + + + + + + + + + + + + + + + + + + + + bilateral trade + trade via market platform + + + + + + + + + + + + + AGR + + + + + + + + + + + + + + + + DSO + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Exchange + € + + + + + + + + + \ No newline at end of file diff --git a/specifications/development/docs/assets/images/image3.emf.odg.svg.license b/specifications/development/docs/assets/images/image3.emf.odg.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image3.emf.odg.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image3.emf.odg.svg.png b/specifications/development/docs/assets/images/image3.emf.odg.svg.png new file mode 100644 index 00000000..7a3876d0 Binary files /dev/null and b/specifications/development/docs/assets/images/image3.emf.odg.svg.png differ diff --git a/specifications/development/docs/assets/images/image3.emf.odg.svg.png.license b/specifications/development/docs/assets/images/image3.emf.odg.svg.png.license new file mode 100644 index 00000000..49cbec7e --- /dev/null +++ b/specifications/development/docs/assets/images/image3.emf.odg.svg.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image4.emf b/specifications/development/docs/assets/images/image4.emf new file mode 100644 index 00000000..387e3eed Binary files /dev/null and b/specifications/development/docs/assets/images/image4.emf differ diff --git a/specifications/development/docs/assets/images/image4.emf.license b/specifications/development/docs/assets/images/image4.emf.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image4.emf.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image4.emf.odg b/specifications/development/docs/assets/images/image4.emf.odg new file mode 100644 index 00000000..da43bb9e Binary files /dev/null and b/specifications/development/docs/assets/images/image4.emf.odg differ diff --git a/specifications/development/docs/assets/images/image4.emf.odg.license b/specifications/development/docs/assets/images/image4.emf.odg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image4.emf.odg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image4.emf.odg.svg b/specifications/development/docs/assets/images/image4.emf.odg.svg new file mode 100644 index 00000000..21bd8023 --- /dev/null +++ b/specifications/development/docs/assets/images/image4.emf.odg.svg @@ -0,0 +1,239 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + AGR + + + + + + + + + + + + + + + + DSO + + + + + + + + + + + + + + + + + + + + + + + + + + + + + bilateral trade + flex trade + + + + + + + + + + + + + AGR + + + + + + + + + + + + + + + + DSO + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + TSO/DSO + coordination + platform + + + + + + + + + + + + flex needs + + + + + + + + + \ No newline at end of file diff --git a/specifications/development/docs/assets/images/image4.emf.odg.svg.license b/specifications/development/docs/assets/images/image4.emf.odg.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image4.emf.odg.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image4.emf.odg.svg.png b/specifications/development/docs/assets/images/image4.emf.odg.svg.png new file mode 100644 index 00000000..b03054fe Binary files /dev/null and b/specifications/development/docs/assets/images/image4.emf.odg.svg.png differ diff --git a/specifications/development/docs/assets/images/image4.emf.odg.svg.png.license b/specifications/development/docs/assets/images/image4.emf.odg.svg.png.license new file mode 100644 index 00000000..49cbec7e --- /dev/null +++ b/specifications/development/docs/assets/images/image4.emf.odg.svg.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image5.png b/specifications/development/docs/assets/images/image5.png new file mode 100644 index 00000000..1d7de0b4 Binary files /dev/null and b/specifications/development/docs/assets/images/image5.png differ diff --git a/specifications/development/docs/assets/images/image5.png.license b/specifications/development/docs/assets/images/image5.png.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image5.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image6.png b/specifications/development/docs/assets/images/image6.png new file mode 100644 index 00000000..41790e05 Binary files /dev/null and b/specifications/development/docs/assets/images/image6.png differ diff --git a/specifications/development/docs/assets/images/image6.png.license b/specifications/development/docs/assets/images/image6.png.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image6.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image8.emf b/specifications/development/docs/assets/images/image8.emf new file mode 100644 index 00000000..4a9b36a7 Binary files /dev/null and b/specifications/development/docs/assets/images/image8.emf differ diff --git a/specifications/development/docs/assets/images/image8.emf.license b/specifications/development/docs/assets/images/image8.emf.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image8.emf.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image8.emf.odg b/specifications/development/docs/assets/images/image8.emf.odg new file mode 100644 index 00000000..b2a3d2d2 Binary files /dev/null and b/specifications/development/docs/assets/images/image8.emf.odg differ diff --git a/specifications/development/docs/assets/images/image8.emf.odg.license b/specifications/development/docs/assets/images/image8.emf.odg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image8.emf.odg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image8.emf.odg.svg b/specifications/development/docs/assets/images/image8.emf.odg.svg new file mode 100644 index 00000000..85e03c22 --- /dev/null +++ b/specifications/development/docs/assets/images/image8.emf.odg.svg @@ -0,0 +1,76 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/specifications/development/docs/assets/images/image8.emf.odg.svg.license b/specifications/development/docs/assets/images/image8.emf.odg.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/image8.emf.odg.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/image8.emf.odg.svg.png b/specifications/development/docs/assets/images/image8.emf.odg.svg.png new file mode 100644 index 00000000..6e0fb747 Binary files /dev/null and b/specifications/development/docs/assets/images/image8.emf.odg.svg.png differ diff --git a/specifications/development/docs/assets/images/image8.emf.odg.svg.png.license b/specifications/development/docs/assets/images/image8.emf.odg.svg.png.license new file mode 100644 index 00000000..49cbec7e --- /dev/null +++ b/specifications/development/docs/assets/images/image8.emf.odg.svg.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/shapeshifter-horizontal-color.svg b/specifications/development/docs/assets/images/shapeshifter-horizontal-color.svg new file mode 100644 index 00000000..0ecadbee --- /dev/null +++ b/specifications/development/docs/assets/images/shapeshifter-horizontal-color.svg @@ -0,0 +1,179 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/specifications/development/docs/assets/images/shapeshifter-horizontal-color.svg.license b/specifications/development/docs/assets/images/shapeshifter-horizontal-color.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/shapeshifter-horizontal-color.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/shapeshifter-horizontal-color.svg.png b/specifications/development/docs/assets/images/shapeshifter-horizontal-color.svg.png new file mode 100644 index 00000000..66321ca2 Binary files /dev/null and b/specifications/development/docs/assets/images/shapeshifter-horizontal-color.svg.png differ diff --git a/specifications/development/docs/assets/images/shapeshifter-horizontal-color.svg.png.license b/specifications/development/docs/assets/images/shapeshifter-horizontal-color.svg.png.license new file mode 100644 index 00000000..49cbec7e --- /dev/null +++ b/specifications/development/docs/assets/images/shapeshifter-horizontal-color.svg.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/shapeshifter-icon-color.svg b/specifications/development/docs/assets/images/shapeshifter-icon-color.svg new file mode 100644 index 00000000..4cf66ceb --- /dev/null +++ b/specifications/development/docs/assets/images/shapeshifter-icon-color.svg @@ -0,0 +1,118 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/specifications/development/docs/assets/images/shapeshifter-icon-color.svg.license b/specifications/development/docs/assets/images/shapeshifter-icon-color.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/shapeshifter-icon-color.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/shapeshifter-icon-color.svg.png b/specifications/development/docs/assets/images/shapeshifter-icon-color.svg.png new file mode 100644 index 00000000..4e6df1be Binary files /dev/null and b/specifications/development/docs/assets/images/shapeshifter-icon-color.svg.png differ diff --git a/specifications/development/docs/assets/images/shapeshifter-icon-color.svg.png.license b/specifications/development/docs/assets/images/shapeshifter-icon-color.svg.png.license new file mode 100644 index 00000000..49cbec7e --- /dev/null +++ b/specifications/development/docs/assets/images/shapeshifter-icon-color.svg.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/shapeshifter-icon-white.svg b/specifications/development/docs/assets/images/shapeshifter-icon-white.svg new file mode 100644 index 00000000..37a343a5 --- /dev/null +++ b/specifications/development/docs/assets/images/shapeshifter-icon-white.svg @@ -0,0 +1,110 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/specifications/development/docs/assets/images/shapeshifter-icon-white.svg.license b/specifications/development/docs/assets/images/shapeshifter-icon-white.svg.license new file mode 100644 index 00000000..e24a032b --- /dev/null +++ b/specifications/development/docs/assets/images/shapeshifter-icon-white.svg.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2020-2023 Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/assets/images/shapeshifter-icon-white.svg.png b/specifications/development/docs/assets/images/shapeshifter-icon-white.svg.png new file mode 100644 index 00000000..01a4c8b7 Binary files /dev/null and b/specifications/development/docs/assets/images/shapeshifter-icon-white.svg.png differ diff --git a/specifications/development/docs/assets/images/shapeshifter-icon-white.svg.png.license b/specifications/development/docs/assets/images/shapeshifter-icon-white.svg.png.license new file mode 100644 index 00000000..49cbec7e --- /dev/null +++ b/specifications/development/docs/assets/images/shapeshifter-icon-white.svg.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: Contributors to the Shapeshifter project + +SPDX-License-Identifier: Apache-2.0 diff --git a/specifications/development/docs/diagrams/contract-phase.puml b/specifications/development/docs/diagrams/contract-phase.puml new file mode 100644 index 00000000..dea7f40c --- /dev/null +++ b/specifications/development/docs/diagrams/contract-phase.puml @@ -0,0 +1,16 @@ +@startuml +!theme cerulean + +participant AGR +participant CRO +participant DSO + +== Contract == +AGR <-> DSO: Pre-qualification AGR +AGR -> AGR: contract Prosumers +CRO <- DSO: publish congestion points incl. connections +AGR -> CRO: publish connections related to contracted Prosumers +AGR <-> DSO: [optional] negotiate FlexOption +DSO -> DSO: Pre-Q asset(s) + +@enduml \ No newline at end of file diff --git a/specifications/development/docs/diagrams/operate-phase.puml b/specifications/development/docs/diagrams/operate-phase.puml new file mode 100644 index 00000000..b439b61f --- /dev/null +++ b/specifications/development/docs/diagrams/operate-phase.puml @@ -0,0 +1,16 @@ +@startuml +!theme cerulean + +participant AGR +participant DSO + +== Operate == +DSO -> DSO: Grid safety analysis -> NOK +DSO -> DSO: Evaluate offers +AGR <- DSO: FlexOrder +AGR -> AGR: control portfolio +AGR -> DSO: (updated) D-prognosis +AGR -> AGR: reconsider offer +AGR -> DSO: FlexOfferRevocation + +@enduml \ No newline at end of file diff --git a/specifications/development/docs/diagrams/plan-phase.puml b/specifications/development/docs/diagrams/plan-phase.puml new file mode 100644 index 00000000..2a7b4c5d --- /dev/null +++ b/specifications/development/docs/diagrams/plan-phase.puml @@ -0,0 +1,15 @@ +@startuml +!theme cerulean + +participant AGR +participant CRO +participant DSO + +== Plan == +AGR -> CRO: Retrieve list congestion points incl. associated connections +CRO <- DSO: Retrieve 'active' Aggregators for each congestion point +AGR -> AGR: optimize portfolio +AGR <- DSO: [optional] FlexReservationUpdate +AGR -> AGR: optimize portfolio + +@enduml \ No newline at end of file diff --git a/specifications/development/docs/diagrams/settle-phase.puml b/specifications/development/docs/diagrams/settle-phase.puml new file mode 100644 index 00000000..910c46fa --- /dev/null +++ b/specifications/development/docs/diagrams/settle-phase.puml @@ -0,0 +1,20 @@ +@startuml +!theme cerulean + +participant AGR +participant DSO + +== Settle == +group par +AGR -> AGR: calculate sold flexibility +DSO -> DSO: calculate procured flexibility +DSO -> DSO: collect meter data +AGR -> AGR: validate if baselines are met +AGR -> AGR: calculate flex fee (and penalty) +DSO -> DSO: calculate flex fee (and penalty) +end +AGR <- DSO: FlexSettlement +AGR -> AGR: validate with own calculations +AGR -> DSO: Response: accepted OR disputed + +@enduml \ No newline at end of file diff --git a/specifications/development/docs/diagrams/use-case-3-1-exchange-of-congestions-points.puml b/specifications/development/docs/diagrams/use-case-3-1-exchange-of-congestions-points.puml new file mode 100644 index 00000000..57b221f6 --- /dev/null +++ b/specifications/development/docs/diagrams/use-case-3-1-exchange-of-congestions-points.puml @@ -0,0 +1,23 @@ +@startuml +!theme cerulean + +participant DSO +participant CRO + +DSO -> CRO: DSOPortfolioUpdate +DSO <-- CRO: HTTP OK + +alt if CRO is operating in open mode + DSO <- CRO: DSOPortfolioUpdateResponse Result=Accepted + DSO --> CRO: HTTP OK +else + alt if DSO is an authorized participant + DSO <- CRO: DSOPortfolioUpdateResponse Result=Accepted + DSO --> CRO: HTTP OK + else + DSO <- CRO: DSOPortfolioUpdateResponse Result=Rejected + DSO --> CRO: HTTP OK + end +end + +@enduml \ No newline at end of file diff --git a/specifications/development/docs/diagrams/use-case-3-10-exchange-of-flexorder-direct.puml b/specifications/development/docs/diagrams/use-case-3-10-exchange-of-flexorder-direct.puml new file mode 100644 index 00000000..da0d9adf --- /dev/null +++ b/specifications/development/docs/diagrams/use-case-3-10-exchange-of-flexorder-direct.puml @@ -0,0 +1,18 @@ +@startuml +!theme cerulean + +participant AGR +participant DSO + +AGR <- DSO: FlexOrder +AGR --> DSO: HTTP OK + +alt if FlexOrder is valid + AGR -> DSO: FlexOrderResponse Result=Accepted + AGR <-- DSO: HTTP OK +else + AGR -> DSO: FlexOrderResponse Result=Rejected + AGR <-- DSO: HTTP OK +end + +@enduml \ No newline at end of file diff --git a/specifications/development/docs/diagrams/use-case-3-10-exchange-of-flexorder.puml b/specifications/development/docs/diagrams/use-case-3-10-exchange-of-flexorder.puml new file mode 100644 index 00000000..b9e22592 --- /dev/null +++ b/specifications/development/docs/diagrams/use-case-3-10-exchange-of-flexorder.puml @@ -0,0 +1,20 @@ +@startuml +!theme cerulean + +participant AGR +participant DSO + +loop for each available FlexOffer to be accepted + AGR <- DSO: FlexOrder + AGR --> DSO: HTTP OK + + alt if FlexOrder is valid + AGR -> DSO: FlexOrderResponse Result=Accepted + AGR <-- DSO: HTTP OK + else + AGR -> DSO: FlexOrderResponse Result=Rejected + AGR <-- DSO: HTTP OK + end +end + +@enduml \ No newline at end of file diff --git a/specifications/development/docs/diagrams/use-case-3-11-transmission-of-settlement.puml b/specifications/development/docs/diagrams/use-case-3-11-transmission-of-settlement.puml new file mode 100644 index 00000000..d0c7ba3d --- /dev/null +++ b/specifications/development/docs/diagrams/use-case-3-11-transmission-of-settlement.puml @@ -0,0 +1,25 @@ +@startuml +!theme cerulean + +participant AGR +participant DSO + +AGR <- DSO: FlexSettlement +AGR --> DSO: HTTP OK + +alt if FlexSettlement is valid + loop for each FlexOrderSettlement in FlexSettlement + alt if settlement details are accepted + AGR -> AGR: ...Disposition=Accepted + else + AGR -> AGR: ...Disposition=Rejected + end + end + AGR -> DSO: FlexSettlementResponse Result=Accepted + AGR <-- DSO: HTTP OK +else + AGR -> DSO: FlexSettlementResponse Result=Rejected + AGR <-- DSO: HTTP OK +end + +@enduml \ No newline at end of file diff --git a/specifications/development/docs/diagrams/use-case-3-2-exchange-of-connections-by-agr.puml b/specifications/development/docs/diagrams/use-case-3-2-exchange-of-connections-by-agr.puml new file mode 100644 index 00000000..40eaec3b --- /dev/null +++ b/specifications/development/docs/diagrams/use-case-3-2-exchange-of-connections-by-agr.puml @@ -0,0 +1,23 @@ +@startuml +!theme cerulean + +participant AGR +participant CRO + +AGR -> CRO: AGRPortfolioUpdate +AGR <-- CRO: HTTP OK + +alt if CRO is operating in open mode + AGR <- CRO: AGRPortfolioUpdateResponse Result=Accepted + AGR --> CRO: HTTP OK +else + alt if AGR is an authorized participant + AGR <- CRO: AGRPortfolioUpdateResponse Result=Accepted + AGR --> CRO: HTTP OK + else + AGR <- CRO: AGRPortfolioUpdateResponse Result=Rejected + AGR --> CRO: HTTP OK + end +end + +@enduml \ No newline at end of file diff --git a/specifications/development/docs/diagrams/use-case-3-3-retrieval-of-congestion-points.puml b/specifications/development/docs/diagrams/use-case-3-3-retrieval-of-congestion-points.puml new file mode 100644 index 00000000..aa9e391d --- /dev/null +++ b/specifications/development/docs/diagrams/use-case-3-3-retrieval-of-congestion-points.puml @@ -0,0 +1,23 @@ +@startuml +!theme cerulean + +participant AGR +participant CRO + +AGR -> CRO: AGRPortfolioQuery +AGR <-- CRO: HTTP OK + +alt if CRO is operating in open mode + AGR <- CRO: AGRPortfolioQueryResponse Result=Accepted + AGR --> CRO: HTTP OK +else + alt if AGR is an authorized participant + AGR <- CRO: AGRPortfolioQueryResponse Result=Accepted + AGR --> CRO: HTTP OK + else + AGR <- CRO: AGRPortfolioQueryResponse Result=Rejected + AGR --> CRO: HTTP OK + end +end + +@enduml \ No newline at end of file diff --git a/specifications/development/docs/diagrams/use-case-3-4-retrieval-of-registered-connections.puml b/specifications/development/docs/diagrams/use-case-3-4-retrieval-of-registered-connections.puml new file mode 100644 index 00000000..4b6537d5 --- /dev/null +++ b/specifications/development/docs/diagrams/use-case-3-4-retrieval-of-registered-connections.puml @@ -0,0 +1,23 @@ +@startuml +!theme cerulean + +participant DSO +participant CRO + +DSO -> CRO: DSOPortfolioQuery +DSO <-- CRO: HTTP OK + +alt if CRO is operating in open mode + DSO <- CRO: DSOPortfolioQueryResponse Result=Accepted + DSO --> CRO: HTTP OK +else + alt if DSO is an authorized participant + DSO <- CRO: DSOPortfolioQueryResponse Result=Accepted + DSO --> CRO: HTTP OK + else + DSO <- CRO: DSOPortfolioQueryResponse Result=Rejected + DSO --> CRO: HTTP OK + end +end + +@enduml \ No newline at end of file diff --git a/specifications/development/docs/diagrams/use-case-3-5-exchange-of-flexreservationupdate.puml b/specifications/development/docs/diagrams/use-case-3-5-exchange-of-flexreservationupdate.puml new file mode 100644 index 00000000..ddd1243c --- /dev/null +++ b/specifications/development/docs/diagrams/use-case-3-5-exchange-of-flexreservationupdate.puml @@ -0,0 +1,20 @@ +@startuml +!theme cerulean + +participant AGR +participant DSO + +loop for each contracted flex reservation in a certain period + AGR <- DSO: FlexReservationUpdate + AGR --> DSO: HTTP OK + + alt if FlexReservationUpdate is valid + AGR -> DSO: FlexReservationUpdateResponse Result=Accepted + AGR <-- DSO: HTTP OK + else + AGR -> DSO: FlexReservationUpdateResponse Result=Rejected + AGR <-- DSO: HTTP OK + end +end + +@enduml \ No newline at end of file diff --git a/specifications/development/docs/diagrams/use-case-3-6-exchange-of-d-prognoses.puml b/specifications/development/docs/diagrams/use-case-3-6-exchange-of-d-prognoses.puml new file mode 100644 index 00000000..807d1a55 --- /dev/null +++ b/specifications/development/docs/diagrams/use-case-3-6-exchange-of-d-prognoses.puml @@ -0,0 +1,20 @@ +@startuml +!theme cerulean + +participant AGR +participant DSO + +loop for each Congestion Point with contracted Prosumers + AGR -> DSO: D-Prognosis + AGR <-- DSO: HTTP OK + + alt if D-Prognosis is valid + AGR -> DSO: D-PrognosisResponse Result=Accepted + AGR <-- DSO: HTTP OK + else + AGR -> DSO: D-PrognosisResponse Result=Rejected + AGR <-- DSO: HTTP OK + end +end + +@enduml \ No newline at end of file diff --git a/specifications/development/docs/diagrams/use-case-3-7-exchange-of-flexrequests.puml b/specifications/development/docs/diagrams/use-case-3-7-exchange-of-flexrequests.puml new file mode 100644 index 00000000..2f211f7a --- /dev/null +++ b/specifications/development/docs/diagrams/use-case-3-7-exchange-of-flexrequests.puml @@ -0,0 +1,20 @@ +@startuml +!theme cerulean + +participant AGR +participant DSO + +loop for each Congestion Point with expected congestion in a certain period + AGR <- DSO: FlexRequest + AGR --> DSO: HTTP OK + + alt if FlexRequest is valid + AGR -> DSO: FlexRequestResponse Result=Accepted + AGR <-- DSO: HTTP OK + else + AGR -> DSO: FlexRequestResponse Result=Rejected + AGR <-- DSO: HTTP OK + end +end + +@enduml \ No newline at end of file diff --git a/specifications/development/docs/diagrams/use-case-3-8-exchange-of-flexoffers.puml b/specifications/development/docs/diagrams/use-case-3-8-exchange-of-flexoffers.puml new file mode 100644 index 00000000..90ddbd5d --- /dev/null +++ b/specifications/development/docs/diagrams/use-case-3-8-exchange-of-flexoffers.puml @@ -0,0 +1,20 @@ +@startuml +!theme cerulean + +participant AGR +participant DSO + +loop for each open flexibility request or unsolicited flexibility offer + AGR -> DSO: FlexOffer + AGR <-- DSO: HTTP OK + + alt if FlexOffer is valid + AGR <- DSO: FlexOfferResponse Result=Accepted + AGR --> DSO: HTTP OK + else + AGR <- DSO: FlexOfferResponse Result=Rejected + AGR --> DSO: HTTP OK + end +end + +@enduml \ No newline at end of file diff --git a/specifications/development/docs/diagrams/use-case-3-9-revocation-of-flexoffer.puml b/specifications/development/docs/diagrams/use-case-3-9-revocation-of-flexoffer.puml new file mode 100644 index 00000000..178235fa --- /dev/null +++ b/specifications/development/docs/diagrams/use-case-3-9-revocation-of-flexoffer.puml @@ -0,0 +1,20 @@ +@startuml +!theme cerulean + +participant AGR +participant DSO + +loop for each open successfully transmitted FlexOffer to be revoked + AGR -> DSO: FlexOfferRevocation + AGR <-- DSO: HTTP OK + + alt if FlexOfferRevocation is valid + AGR <- DSO: FlexOfferRevocationResponse Result=Accepted + AGR --> DSO: HTTP OK + else + AGR <- DSO: FlexOfferRevocationResponse Result=Rejected + AGR --> DSO: HTTP OK + end +end + +@enduml \ No newline at end of file diff --git a/specifications/development/docs/diagrams/validate-phase-direct-flexorder.puml b/specifications/development/docs/diagrams/validate-phase-direct-flexorder.puml new file mode 100644 index 00000000..ca4b2b61 --- /dev/null +++ b/specifications/development/docs/diagrams/validate-phase-direct-flexorder.puml @@ -0,0 +1,13 @@ +@startuml +!theme cerulean + +participant AGR +participant DSO + +== Validate == +DSO -> DSO: Grid safety analysis -> NOK +DSO -> DSO: Select flexibility agreement +AGR <- DSO: FlexOrder +DSO -> DSO: Grid safety analysis -> OK + +@enduml \ No newline at end of file diff --git a/specifications/development/docs/diagrams/validate-phase-gate-closure-time.puml b/specifications/development/docs/diagrams/validate-phase-gate-closure-time.puml new file mode 100644 index 00000000..5134f6e1 --- /dev/null +++ b/specifications/development/docs/diagrams/validate-phase-gate-closure-time.puml @@ -0,0 +1,23 @@ +@startuml +!theme cerulean + +== Validate == +AGR <- DSO: FlexRequest +AGR <- AGR: determine offers +AGR -> DSO: FlexOffer +DSO -> DSO: Evaluate offers +DSO -> AGR: FlexOrder + +== Plan == +AGR -> AGR: re-optimize portfolio + +== Validate == +AGR -> DSO: (updated) D-prognosis +DSO -> DSO: Grid safety analysis -> NOK +AGR <- DSO: FlexRequest +AGR <- AGR: determine offers +AGR -> DSO: FlexOffer + +== Gate closure == + +@enduml \ No newline at end of file diff --git a/specifications/development/docs/diagrams/validate-phase-multiple-flexoffers.puml b/specifications/development/docs/diagrams/validate-phase-multiple-flexoffers.puml new file mode 100644 index 00000000..93378ea1 --- /dev/null +++ b/specifications/development/docs/diagrams/validate-phase-multiple-flexoffers.puml @@ -0,0 +1,15 @@ +@startuml +!theme cerulean + +== Validate == +AGR <- DSO: FlexRequest +AGR <- AGR: determine offers +AGR -> DSO: FlexOffer +AGR -> DSO: FlexOffer +AGR -> DSO: FlexOffer +DSO -> DSO: Evaluate offers +AGR -> AGR: reconsider offer +AGR -> DSO: FlexOfferRevocation +DSO -> DSO: Evaluate offers + +@enduml \ No newline at end of file diff --git a/specifications/development/docs/diagrams/validate-phase.puml b/specifications/development/docs/diagrams/validate-phase.puml new file mode 100644 index 00000000..c73484b7 --- /dev/null +++ b/specifications/development/docs/diagrams/validate-phase.puml @@ -0,0 +1,24 @@ +@startuml +!theme cerulean + +participant AGR as AGR1 +participant AGR as AGR2 +participant DSO + +== Validate == +DSO -> DSO: non-aggregator forecast +AGR1 -> DSO: [optional] D-prognosis +AGR2 -> DSO: [optional] D-prognosis +DSO -> DSO: Grid safety analysis -> NOK +AGR2 <- DSO: FlexRequest +AGR1 <- DSO: FlexRequest +AGR1 <- AGR1: determine offers +AGR2 <- AGR2: determine offers +AGR2 -> DSO: FlexOffer +DSO -> DSO: Evaluate offers +AGR2 <- DSO: FlexOrder +AGR2 -> DSO: [optional] (updated) D-prognosis +DSO -> DSO: Grid safety analysis -> OK +DSO -> DSO: Grid safety analysis -> OK + +@enduml \ No newline at end of file diff --git a/specifications/development/docs/general-description/contract-phase.md b/specifications/development/docs/general-description/contract-phase.md new file mode 100644 index 00000000..c115bb25 --- /dev/null +++ b/specifications/development/docs/general-description/contract-phase.md @@ -0,0 +1,121 @@ + + +# Contract phase + +## Overall description + +The contract phase is when DSOs and AGRs begin interaction. +Typically, this involves a pre-qualification process, where the AGRs capability to deliver flexibility, portfolio and IT systems are assessed. +AGR pre-qualification is out-of-scope for UFTP and therefore not further described in this document. +See [^B6] for more information. +In addition, the contract phase includes the exchange of information related to congestion points and associated connections through the common reference. +Note that any contract negotiations for bilateral contracts also takes place in the contract phase (see below). + +[^B6]: USEF, "Recommended practices and key considerations for a regulatory framework and market design on explicit Demand Response," 2017. [Online]. Available: [https://www.usef.energy/app/uploads/2017/09/Recommended-practices-for-DR-market-design-2.pdf](https://www.usef.energy/app/uploads/2017/09/Recommended-practices-for-DR-market-design-2.pdf). + +
+ ![General information flow in the Contract phase](../diagrams/contract-phase.puml){ .no-lightbox } +
General information flow in the Contract phase
+
+ +As part of its internal grid planning process, a DSO determines where congestion may possibly take place. +Congestion points are declared whenever necessary, most likely several times a year, depending on the volume of trend analyses performed by a DSO and the condition of the grid. +By publishing a particular congestion point, the DSO opens a flexibility market for it. +AGRs publish the customers that they serve in the common reference. +As a result, a DSO can determine whether there is liquidity on its market and AGRs know which of their customers can participate in a DSO’s market. + +USEF introduces two alternative options for the DSO to procure flexibility from AGRs: + +- **Long-term flexibility options:** activation of flexibility options in prearranged bilateral contracts. +Contracts of this nature oblige the AGR to offer a fixed amount of flexibility to the market via daily FlexOffers. +This product guarantees a certain regular availability of flexibility but the price (model) has to be arranged in advance. +As a result, the DSO can select the contract(s) that provide the required flexibility at the lowest costs although these, typically, will not reflect all flexibility available in the market or the actual marginal costs for any flexibility supplied. +This method is comparable to the way in which national TSOs contract balancing services and a tender or auction procedure can be implemented to manage it, alongside long-term flexibility options subject to prearranged specific conditions; e.g. which include a maximum or fixed price for the activation of the flexibility. + +- **Short-term flexibility options:** procuring flexibility that AGRs have offered for a specific day. +In this situation, the AGR has no contractual obligation to offer the flexibility to the market but decides to do so on a day-to-day basis. +This product inherently deals with short-term flexibility which is only valid for a specific day. +The price offered by AGRs will better reflect the marginal costs although the availability of the flexibility in this product is not guaranteed. +This method is comparable with the way market parties are free to offer capacity to the TSO on the secondary and tertiary markets (regulating and reserve power) on a daily basis. + +The first option seems attractive for the DSO as it guarantees a minimum supply of flexibility, therefore reducing availability risks in the validate phase, but this comes at a higher price. +The DSO is responsible for finding the right balance between costs and certainty, while ensuring that grid reliability is always maintained. +It is important to note that both products are part of the same flexibility market and therefore it provides natural growth options for the evolution of flexibility trading. +While, initially, the availability of flexibility supply and demand might be a primary concern for both buyers and sellers, leading them to focus on long-term contracts, this will likely change as the market matures and availability becomes less of an issue. +At that point, both buyers and sellers would be willing to have greater reliance on short-term flexibility which, in turn, would offer increased market liquidity. + +## Bilateral contract: FlexOption + +For long-term flexibility, USEF introduces the **FlexOption**. This type of contract enables the DSO to take an option on future flexibility. In relation to this, USEF specifies that: + +- a FlexOption is a bilateral contract between DSO and AGR to deliver a specified amount of flexibility, at a specific location (i.e. congestion point), for a specified time schedule and duration. +- FlexOptions force the AGR to send flexibility offers when the flexibility requests match the contract details. +- FlexOptions are tradable via secondary markets. + +!!! success "Recommended practice:" + + In order to make FlexOptions attractive to AGRs, a DSO could add remuneration components; e.g. availability remuneration and/or a minimum number of activations. + +A FlexOption contract typically has the following ingredients: + +| Element | Description | Example(s) | +|-------------------------------|----------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------| +| ISPs and durations | The Imbalance Settlement Period (ISP) in which the flexibility should be delivered and the duration of the contract. |
  • Every ISP between 17:00 and 19:00 on Fridays
  • from December through March for the coming two years
| +| Lead time | Time before the (recurring) flexibility option expires. |
  • One week before dispatch
  • The day before dispatch at 16:00
  • Does not expire
| +| Congestion Point | DSO-specific: Congestion Point at which the flexibility should be realized. | | +| Amount | Amount of flexibility being offered, specified as a delta to a baseline value or drop to mechanism. |
  • 10kW (average power per ISP)
| +| Capacity remuneration | Price the AGR receives for offering the flexibility option |
  • €20/MW/day
  • €40/MW/ISP
| +| Volume remuneration | Maximum or predefined price for the flexibility, to be paid when the flexibility is ordered by the DSO. |
  • €20/MWh
  • Less than €20/MWh
  • €0
| +| Maximum number of activations | The Maximum number of activations at which the flexibility in the LT contract can be called upon. |
  • Once per contract
  • Once per month
  • Unlimited
| +| Recovery Time | Minimum time between activiations | | +| Penalties | Amount the AGR is penalized for not offering the option of flexibility and/or the flexibility itself. | n/a | + +UFTP does not include messages to communicate the contents of a FlexOption; this is assumed to be out-of-scope. + +## Common Reference + +A DSO declares its congestion points in the contract phase. +An AGR must be able to retrieve information about these points since this allows it to fulfil its obligation to provide the compulsory D-prognoses to DSOs for congestion points at which it represents customers. +It also aids the AGRs portfolio optimization activities. + +Since a prosumer can switch AGRs, and the congestion points in the grid change over time, USEF introduces a ‘common reference’. +The common reference contains a list of connection identifiers (for example EANs) for each congestion point, as registered by the participating DSOs. +Each AGR also registers the connections on which it represents prosumers. +The common reference is shared between all involved parties, while respecting privacy and security principles [^B5] which ensures, amongst other things, that only necessary information is shared and therefore included in the common reference. +The common reference is operated by the Common Reference Operator (CRO) role. +Conceptually, it contains the entities and relationships shown in the figure below: + +[^B5]: USEF Foundation, "USEF: The Privacy and Security Guideline," USEF Foundation, Arnhem, 2015. Available: [https://www.usef.energy/app/uploads/2016/12/USEF_PrivacySecurityGuideline_3nov15.pdf](https://www.usef.energy/app/uploads/2016/12/USEF_PrivacySecurityGuideline_3nov15.pdf) + +
+ ![Logical structure of the Common Reference](../assets/images/image8.emf.odg.svg.png){ width=1000px } +
Logical structure of the Common Reference
+
+ +The common reference is, typically, setup by the DSO and includes all of its congestion points. +However, it could be extended to form a common reference at national or European grid level. + +UFTP allows for the registering and tracking of changes in the common reference; e.g. a DSO might announce a new congestion point for the following week which is registered in the common reference. +The history of all changes to the common reference is retained and can be retrieved for a certain date using the query function functions (see [AGRPortfolioQuery](../message-descriptions/message-catalog/agr-portfolio-query.md) and [DSOPortfolioUpdate](../message-descriptions/message-catalog/dso-portfolio-update.md)); this will also help resolve any potential disputes. + +### Accessibility of the data in the common reference + +Access to the common reference data is limited according to the legal or contractual requirements of the various parties consulting it[^3]. +This implies that a DSO can only see the data for the connections it is responsible for. +Consequently, it can see which AGRs are serving its connections, in order to ensure that it receives D-prognoses from them. + +AGRs can only see information about the congestion points for which they serve connections. +In addition, they can retrieve the number of connections per congestion point. +Implementing the common reference this way ensures that the DSO does not need to share details of its grid topology. + +The common reference can be operated in two modes: open mode and closed mode. +If operating in open mode, the CRO will accept updates from any USEF-compliant participants. +In closed mode, participants will need to be pre-configured in order for updates to be accepted. + +[^3]: + Another option is to treat the common reference as open data, therefore implying that everyone can access it. + Although the open data model can ease the implementation of the common reference, the acceptance of such a model by prosumers is highly dependent on the culture in the geographical area in which the model is used. diff --git a/specifications/development/docs/general-description/index.md b/specifications/development/docs/general-description/index.md new file mode 100644 index 00000000..5928a06b --- /dev/null +++ b/specifications/development/docs/general-description/index.md @@ -0,0 +1,15 @@ + + +# General description + +This chapter describes the global information flows for flexibility trading between AGR and DSO for grid contraint purposes. +In this respect, UFTP acts as a subset of USEF’s market-based coordination mechanism (MCM), where AGR-DSO trading is an embedded part of the broader mechanism which applies to multiple flexibility services for all relevant market roles. +In order to understand how UFTP is embedded in USEF, we have used some of USEF’s general concepts to describe the UFTP processes. +For further information on these, please see ‘USEF: The Framework explained’ [^B1]. +Sections describe the interactions in the different Phases of MCM: [Contract](contract-phase.md), [Plan](plan-phase.md), [Validate](validate-phase.md), [Operate](operate-phase.md) and [Settle](settle-phase.md). + +[^B1]: USEF, "Flexibility Value Chain (update 2018)," 8 10 2018. [Online]. Available: [https://www.usef.energy/app/uploads/2018/11/USEF-White-paper-Flexibility-Value-Chain-2018-version-1.0_Oct18.pdf](https://www.usef.energy/app/uploads/2018/11/USEF-White-paper-Flexibility-Value-Chain-2018-version-1.0_Oct18.pdf). diff --git a/specifications/development/docs/general-description/operate-phase.md b/specifications/development/docs/general-description/operate-phase.md new file mode 100644 index 00000000..a4d6ca8c --- /dev/null +++ b/specifications/development/docs/general-description/operate-phase.md @@ -0,0 +1,39 @@ + + +# Operate phase + +While (similar to the current liberalized energy market) the total energy system will remain in balance, without any congestion issues, as long as there are no deviations from the plans, it is unlikely that all plans will be executed exactly. +Deviations can arise from a range of sources, ranging from changing weather expectations to an extension of a football match. +Deviations can lead to: imbalances in supply and demand of energy at total system level (affecting the BRP); changes within the AGR portfolio (affecting the AGR); and local congestion in the distribution system (affecting the DSO). +USEF’s MCM is designed such that, during the operate phase, additional flexibility can be applied in order to compensate for these deviations. +The processes for invoking this flexibility are depicted in the following figure. + + + +
+ ![General information flows in the Operate phase.](../diagrams/operate-phase.puml){ .no-lightbox } +
General information flows in the Operate phase.
+
+ +During the operate phase, the AGR’s main goal is to adhere to its plan and respect the D-prognoses.[^12] +In order to achieve this, FlexOfferRevocation the AGR must first plan to ensure assets operate in accordance with its forecast portfolio performance and that any flexibility sold is actually delivered. + +[^12]: UFTP allows for alternative baselines, see [General description](index.md). In case of alternative baselines, D-prognosis is optional. + +Next, the AGR measures the net demand or supply of its portfolio, in order to detect deviations from its plan and D-prognoses. +Where deviations occur, the AGR re-optimizes its portfolio. +It is possible that deviations could be solved using the flexibility contained within the portfolio itself. + +If this is not the case, the AGR must change its plan (and probably limit its liabilities due to non-performance, to minimize fines) and control the assets to ensure that the new plans are realized and send an updated D-prognosis. +If a FlexOrder has already been accepted, but the AGR is no longer able to comply, the AGR should inform the DSO as soon as possible through direct means outside of the UFTP protocol. +During the operate phase, the AGR may wish to revoke outstanding (i.e. not ordered) FlexOffers if it is no longer able or willing to deliver the flexibility. + +Although the DSO will reduce congestion risks in the validate phase, the DSO can still request that AGRs dispatch flexible power options to resolve potential grid problems in the operate phase. +Again, due to time constraints, this will be done based on flexibility offers from the validate phase, which are still valid. +When this flexibility is used, the corresponding BRP portfolio will no longer be in balance. +Where the AGR is responsible for the balance, it will most likely charge the additional costs to the DSO. +This is not considered further. diff --git a/specifications/development/docs/general-description/plan-phase.md b/specifications/development/docs/general-description/plan-phase.md new file mode 100644 index 00000000..566b9023 --- /dev/null +++ b/specifications/development/docs/general-description/plan-phase.md @@ -0,0 +1,31 @@ + + +# Plan phase + +USEF’s plan phase aims to find an economically optimized program to supply the energy demand of both AGR and BRP portfolios for a certain period. +In this phase, the AGR optimizes its portfolio and typically arbitrages between different flexibility markets to maximize the value of the available flexibility. +The result of this process is a balanced portfolio. +The exchange between AGR and BRP’s and corresponding trades on the energy markets are out-of-scope for UFTP. +The result, however, will lead to a D-prognosis in the validate phase. + +The processes that take place during the plan phase are schematically depicted in the following figure. + +
+ ![General information flow in the Plan phase](../diagrams/plan-phase.puml){ .no-lightbox } +
General information flow in the Plan phase
+
+ +Since the list of connections belonging to a congestion point, and the list of customers that are served by the AGR, may switch from day to day, USEF specifies that this information is requested on a day-to-day basis. + +The AGRs portfolio optimization is out-of-scope and depicted only for reference. +See [^3] for a detailed description of this process. +For UFTP, it is important to realize that the AGR optimizes its portfolio based on its clients’ needs, optionally taking into account its long-term contractual obligations. + +For bilateral contracts, the DSO might provide a FlexReservationUpdate message e.g. signaling which part of the contracted volume is still reserved and which part is not needed and may be used for other purposes. +This will typically re-trigger the AGRs portfolio optimization process. More information about the flex reservation mechanism is added in [Rationale for information exchange in flexibility request](../appendix/rationale-for-information-exchange-in-flexibility-request.md). + +[^3]: USEF, "USEF - The FrameWork Specifications 2015," 2015. [Online]. diff --git a/specifications/development/docs/general-description/settle-phase.md b/specifications/development/docs/general-description/settle-phase.md new file mode 100644 index 00000000..69d10ca5 --- /dev/null +++ b/specifications/development/docs/general-description/settle-phase.md @@ -0,0 +1,137 @@ + + +# Settle phase + +## Overall description + +In the settle phase, the AGR is remunerated for the delivered flexibility. +There should be a check first, to ensure that the procured flexibility was actually delivered. +A penalty may be applied when there is a mismatch between the baseline and the actual profile. +Except for metering data, USEF assumes that both AGR and DSO have all the information to make these calculations. +The DSO sends its calculation to the AGR for verification. + +
+ ![General information flow flex settlement between DSO and AGR](../diagrams/settle-phase.puml){ .no-lightbox } +
General information flow flex settlement between DSO and AGR
+
+ +In order to perform the settlement, it is necessary for the DSO to compare the metering for each ISP against the baseline, as contained in the demand-prognosis message. +In some regions the metering for the ISP periods for the fiscal meter may already be available to the DSO, through its own systems. +However, where the DSO does not have access to the meter data, or where plant metering is used for settlement assessment, the metering data must be communicated to the DSO by the AGR. +For this purpose the AGR will use the Metering messages to send the daily metering per ISP from each connection point. + +**Recommended Practice:** It is recommended to the include the Power profile in the settlement messages. + +Each month, the DSO will calculate the flexibility settlement volumes and prices for each AGR according to the steps below. + +1. **Calculate procured flexibility**
+For each congestion point and ISP, both the volumes and prices of the acquired flexibility are collected. +2. **Gather Metering Data**
+This is done either based on the DSO’s own metering records or using the metering message +3. **Validate if baselines are met**
+This step is only performed where flexibility has been procured from the specific AGR, for a congestion point and ISP. +The deviation between the final forecast (taking into account all procured flexibility) and the realized profile is calculated. +4. **Calculate flex settlement volumes and prices**
+The settlement volumes and prices are calculated (see example below). +5. **Send settlement message to AGR**
+This shows, per month, the accumulated settlement volume, accumulated deviation from the agreed baselines, and accumulated settlement price (accumulated over the ISPs and the congestion points). + +The AGR will use its own information to do the same calculations + +1. **Calculate sold flexibility** (equivalent to 1) +2. **Validate if baselines are met** (equivalent to 2) +3. **Plausibility check** (equivalent to 3)
+The results are compared to the settlement message received from the DSO. + +If the difference in the previous plausibility check is within limits, the AGR sends an acknowledgement to the DSO. +If the difference exceeds predefined limits, the DSO’s calculation is disputed. +This is signaled via the SettlementResponseMessage. +The dispute process is not part of USEF. + +## Settlement details + +The DSO is responsible for settling the flexibility that it has acquired from the AGR. +Within this settlement, the DSO needs to check whether the acquired flexibility has been delivered according to the agreements. +Penalties can arise where agreements have not been met and this is considered an integral part of the settlement process. + +This section describes how the supply of flexibility from the AGR to the DSO is settled. +Several methods are possible, depending on how the flexibility is offered to the DSO and, more precisely, whether the DSO uses the mechanism of long-term and short- term flex options, and whether these flex options are rewarded, even if they are not exercised. +Passive contribution to constraint management may also be rewarded. + +Calculations are (in general) performed at ISP level, with settlement calculated over a one-month period. + +### Settlement components + +The settlement consists of five components: + +1. **Settlement of acquired flexibility**
+The DSO will acquire flexibility through the market mechanism if congestion is expected, either ahead of time (validate phase) or real-time (operate phase). +On average, the market price is determined by the equilibrium of demanded and offered flexibility (merit order). +Following the recommendation given in Section [Flexibility trading between the AGR and DSO](validate-phase.md#flexibility-trading-between-the-agr-and-dso), pay-as-bid pricing is used for individual settlements. +2. **Settlement of deviations from baselines**
+AGRs that have sold flexibility to the DSO need to limit their capacity to the value stated in the baseline, corrected for the sold flexibility. +A penalty is raised for each ISP where the agreed capacity has (on average) been exceeded. +The penalty is single sided, meaning that the AGR is allowed to deviate from its baseline as long as the deviation contributes to avoiding the grid constraint. +3. **[optional] Settlement of long-term flexibility options (bilateral contracts)**
+The DSO may acquire long-term flexibility options to ensure that congestion can be avoided at all times. +This may be necessary to justify a decision to delay or defer grid investments, or where grid constraints are expected in the (near) future. +The DSO will determine (e.g. through audits) that the AGR is always capable of providing the contracted flexibility (at contracted times). +4. **[optional] Settlement of short-term flexibility options (FlexOffers which are not procured)**
+When grid constraints are expected during the validate phase by the DSO, all AGRs are asked to place flexibility offers. +AGRs whose flexibility bids are accepted by the DSO are expected to meet their (adjusted) baselines. +However, it is just as important for the DSO that the other AGRs are also bound to their baselines. +To enforce and reward this, the DSO may also accept an option on the flexibility offered by the AGR, even if the bid is not accepted, to ensure the AGR will not jeopardize grid constraints by invoking its flexibility for other purposes. +The DSO will pay the AGR for the option, as this will put a constraint on the total capacity of the AGRs portfolio. +5. **[Optional] Settlement of passive contribution to constraint management**
+Possible reward for AGRs that passively support the management of grid constraints – either by staying below the agreed value expressed in their baselines or by reducing more power than agreed in the exercised flexibility bid. +This is specifically relevant if constraints have been resolved by passive contributions, where other AGRs have exceeded the agreed capacities. +In this situation, the passive contribution can be rewarded using the raised penalties (zero sum calculations). + +The settlement method implicitly assumes that each AGR has the motivation and capacity to produce high quality baselines. + +### Settlement calculations + +(numbers refer to the settlement components above) + +| Nr. | Amount | P = | Q = | Remark(s) | +|-------|------------|---------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **1** | P x Q | P = flexiblity fee | Q = power called ("Delivered Flex Quantity") | The flexibility fee is determined by the equilibrium of demanded and offered flexibility (flexibility market). | +| **2** | P x Q | P = excess penalty (asymmetrical, only applied when deviation has contributed to congestion) | Q = allocation – initial baseline – Σ FlexOrders ("Power Deficiency Quantity"), where allocation is the average realized power during the ISP | This penalty only applies to AGRs that have sold flexibility (for this ISP), and corresponds with not meeting the agreements of the flexibility bid. | +| **3** | negotiated | n.a. | n.a. | The DSO will pay compensation for the long-term flexibility contract in proportion to the agreed power, the duration of the time slot, the nomination lead-time and the duration of the contract. Fixed fee may be derived from:
  • The costs for allowing thermal limitations to be violated;
  • The avoided costs for grid reinforcements;
  • The value of flexibility for alternative uses;
  • The costs of alternative flexibility options.
| +| **4** | P x Q | P = flexibility option fee | Q = power option | In this settlement component, an AGR can be rewarded for participating in the flexibility market through short-term products. Rationale for relating the flexibility option settlement to the capacity offered is that an option to cap the capacity of an AGR with twice the capacity of another AGR, has twice the value to the DSO. | +| **5** | P x Q | P = contribution fee (asymmetrical, only applied when deviation has relieved congestion). Derived from excess penalties raised. | Q = allocation - baselines – power flexibility called during Operate phase where allocation is the average realized power during the ISP. | | + +### Settlement example + +For a specific ISP we assume: + +- The AGR has specified a total load of 10 MW in its initial baseline +- During one or more flexibility requests, a total of 2 MW of flexibility has been acquired by the DSO, yielding an adjusted baseline of 8 MW +- The table below shows how different realizations are settled. The realization is specified by the allocation, representing the average power during one specific ISP for one congestion point. In this example the following (illustrative) prices are applied: + - Flex price equals 7 € / MW + - Baseline deviation penalty equals 11 € / MW (single sided) + +| Allocation (MW) | Flex realized (MW) | Delivered flex quantity (MW) | Flex paid (€) | baseline deviation (MW) | Power deficiency quantity (MW) | Penalty raised (€) | Settlement (€) | +|-----------------|--------------------|------------------------------|---------------|-------------------------|--------------------------------|--------------------|----------------| +| 7 | 3 | 2 | 14 | -1 | 0 | 0 | 14 | +| 8 | 2 | 2 | 14 | 0 | 0 | 0 | 14 | +| 9 | 1 | 1 | 7 | 1 | 1 | -11 | -4 | +| 10 | 0 | 0 | 0 | 2 | 2 | -22 | -22 | +| 11 | -1 | 0 | 0 | 3 | 3 | -33 | -33 | + +Elaboration of the calculations performed in the table: + +1. _Allocation_ shows possible results of the realization of the AGR portfolio +2. The _flex realized_ equals the baseline associated with the flex offer minus the allocation +3. The delivered _flex quantity_, represents the flexibility that is both acquired (therefore maximum of 2) and delivered. +Passive contributions (as in the row with allocation=7) are not rewarded. +4. The _flex paid_ equals the _delivered flex quantity_ times the flex price +5. The _baseline deviation_ equals the allocation minus the adjusted baseline +6. The _power deficiency quantity_ equals the _baseline deviation_, where negative deviations are set to 0 since these are not penalized. +7. The _penalty raised_ equals the _power deficiency quantity_ times the penalty +8. The settlement price equals the sum of the _flex paid_ and _penalties raised_. +9. The monthly totals of the elements: _delivered flex quantity, power deficiency quantity and Settlement_ are sent to the AGR. diff --git a/specifications/development/docs/general-description/usef-general-concepts.md b/specifications/development/docs/general-description/usef-general-concepts.md new file mode 100644 index 00000000..3f7403ec --- /dev/null +++ b/specifications/development/docs/general-description/usef-general-concepts.md @@ -0,0 +1,101 @@ + + +# USEF general concepts + +## USEF market-based coordination mechanism (MCM) + +USEF’s MCM facilitates the delivery of value propositions (i.e. marketable services) to various market parties without imposing +limitations on the diversity and customization of the propositions. +The USEF MCM is designed for all energy commodities and enables the market to optimize in time, capacity and power. +The MCM provides access, under equal conditions, for all stakeholders to a single integrated market. +This unique approach aims to deliver a future-proof market design. The USEF MCM operations scheme distinguishes five phases: + +![](../assets/images/image5.png) + +In UFTP, the general MCM phases are followed. However, processes in each phase are limited to the interactions between the +AGR and DSO for flexibility trading. This includes interaction with the ‘Common Reference’: + +- **Contract:** AGR and DSO negotiate FlexOptions. +This is flexibility that is reserved for DSO purposes and can be invoked by the DSO when needed. +Typically, a contract includes availability remunerations and activation remunerations. + +- **Plan:** information exchange between DSO and AGRs related to congestion points. +This information exchange through the ‘Common Reference’ involves communication with the Common Reference Operator (CRO). +The AGR carries out an initial portfolio optimization. + +- **Validate:** the DSO uses D-prognoses to validate whether the demand and supply of energy can be distributed safely without any limitations. +If congestion occurs, the DSO can procure flexibility from AGRs to resolve grid capacity issues. + +- **Operate:** in the operate phase, the actual assets and appliances are dispatched and the AGR adheres to its D-prognoses. +When required, DSOs can invoke additional flexibility from AGRs to resolve unexpected congestion. + +- **Settle:** in the settle phase, the flexibility that the AGR has sold to DSOs is settled. +For this purpose, the actual consumed and produced volumes are allocated to the responsible parties first. +Any unresolved or disputed volumes are reconciled shortly afterwards. + +## USEF Operating regimes + +USEF recognizes four different operating regimes. +The green regime is the classical grid without any limitations (copper plate) and the red regime is where power outages occur. +USEF introduces two additional regimes. In the green and yellow regimes, the MCM assures optimal use of the flexibility available for BRPs (green and yellow) and DSOs (yellow). +The orange regime is introduced as a fallback for situations where there is insufficient flexibility available for the DSO to avoid an outage—the DSO can limit connections to temporarily overrule the market. + +
+ ![USEF Operating regimes](../assets/images/image6.png) +
USEF Operating regimes
+
+ + +UFTP flexibility trading takes place solely in the yellow regime. Full descriptions of all other regimes can be found in [^B3]. + +[^B3]: USEF, "USEF - The FrameWork Specifications 2015," 2015. [Online]. + +## Day-head and intraday flexiblity trading + +The plan and validate phases aim to make optimal use of flexibility and maximize the freedom of dispatch and transactions of all stakeholders before the actual delivery of energy takes place. +The timescale of these phases already ranges from years and months ahead, towards one day ahead and, ultimately, hours ahead before the actual delivery of energy (i.e. the operate phase) starts. +This broad time window supports trading on various energy markets (i.e. forward market, day-ahead spot market and intraday spot-market) and the monitoring of changes in the required grid capacity. + +USEF specifies that iterations between the plan and validate phases take place at least twice: initially, during the day ahead and, secondly, during intraday. +Hence, two points in time are determined when the markets close: 1) end of day-ahead 2) end of intraday. +This specification eases the iterative process of creating, aligning and converging plans and D-prognoses and fits well with many current national processes applied in the day ahead and intraday trading market. +Please find more details in [Iterations between the plan and validate phases](validate-phase.md#iterations-between-the-plan-and-validate-phases). + +UFTP supports both day-ahead and intraday trading. Intraday trading is optional for UFTP. + +## Congestions points + +A congestion point is a set of connections which (directly) relate to a part of the grid where grid capacity might be exceeded because it may be insufficient to distribute the requested amount of energy; e.g. the secondary side of an LV transformer. +Please note that a congestion point is a part of the grid where congestion may possibly occur, rather than actually occurs. +It is the DSOs responsibility to determine congestion points. + +!!! success "Recommended practice:" + + How to determine which grid points are congestion points is the DSOs responsibility and therefore outside of the scope of USEF. + However, USEF recommends declaring congestion points at the lowest possible level in the grid as this allows for detailed insight about local congestion while simultaneously, through aggregation, safeguarding the reliability of the grid safety analysis. + +Congestion points are registered in the common reference, see [Common Reference](contract-phase.md#common-reference). + +## Flexiblity market time granularity + +All flexibility exchange in USEF is based on a time granularity that is in line with the imbalance settlement period (ISP)[^2], which is the time unit for which the imbalance of the balance responsible parties is calculated. +For most EU countries this is a 15-minute interval, leading to 96 ISPs per day. +Forecasts, flexibility offers, and orders and settlement are all based on ISPs. +Flexibility is expressed in Power [Watts] which is to be interpreted as the average Power during an ISP. + +[^2]: Commission Regulation (EU) 2017/2195 of 23 November 2017 establishing a guideline on electricity balancing defines an imbalance settlement period (ISP) as the time unit for which the imbalance of the balance responsible parties is calculated (Article 2(10)). + +## Alternative baselines + +All flexibility trading in USEF assumes that flexibility offers take the form of deviation from baseline, i.e. the default situation that would occur if no flexibility were activated. +Typically, the baseline is derived via an AGR nomination referred to as the D-prognosis. +However, UFTP allows for alternative baseline, where a D-prognosis is not required, and it is assumed that the AGR and DSO agree upon the baseline. +An alternative baseline could be based on a measurement (MBMA-method), a mathematical formula or a reference group, etc. +The choice of the alternative baseline and its establishment is out-of-scope for UFTP. +The UFTP trading messages either refer to D-prognosis or to an external baseline reference. +Throughout this document, the D-prognosis is used as the default baseline method. +If UFTP is used with alternative baseline, then all references to the D-prognosis can be ignored. diff --git a/specifications/development/docs/general-description/validate-phase.md b/specifications/development/docs/general-description/validate-phase.md new file mode 100644 index 00000000..0455e9e3 --- /dev/null +++ b/specifications/development/docs/general-description/validate-phase.md @@ -0,0 +1,281 @@ + + +# Validate phase + +## Overall description + +
+ ![Validate phase](../diagrams/validate-phase.puml){ .no-lightbox } +
General information flow in Validate phase
+
+ +Assuming that D-prognoses are used as baseline[^4], each AGR creates a D-prognosis per declared congestion point and sends it to the DSO. +Sending D-prognoses is not required when an alternative baseline method has been agreed. +When all D-prognoses for a congestion point are received, the DSO combines these with the forecasts of non-AGR connections to execute a final grid safety analysis. +This analysis determines whether it is possible to distribute the planned energy, or the limits of the distribution grid are reached. +In the latter situation, USEF moves to the yellow regime and the DSO procures flexibility in the market to resolve these congestion issues. +The process of flexibility trading is as follows: + +[^4]: + UFTP allows for alternative baselines, see [General description](index.md). + In case of alternative baselines, D-prognosis is optional. + +1. The DSO requests all AGRs at the congestion point to provide flexibility. +In this request, the DSO indicates the magnitude (amount of excess power) and timing (ISP) of the expected congestion, and how much capacity is available in the remaining ISPs. This is handled via a _FlexRequest_. +2. AGRs who are able and willing to change their load/generation profile in line with the request create _FlexOffers_. +3. If the offers are a good fit; i.e. help to mitigate congestion, the DSO can procure flexibility by placing a _FlexOrder_. +4. AGRs send an updated D-prognosis which incorporates the flexibility ordered. + +If the flexibility offered is not sufficient to resolve the expected congestion, or no flexibility is offered, USEF moves to the orange regime. +Please note that in this situation, USEF specifies that the DSO procures all offered flexibility from the market (i.e. from the yellow regime) to solve parts of the congestion. +This is because any flexibility offered will still help to reduce the impact of the orange regime (e.g. the number of connections impacted by the graceful degradation). +USEF’s orange regime is outside the scope of UFTP, and, therefore, not further discussed in this document. + +
+ ![Validate phase with multiple FlexOffers](../diagrams/validate-phase-multiple-flexoffers.puml){ .no-lightbox } +
AGR may send multiple FlexOffers on the same request, and open FlexOffers, which are not yet ordered may be revoked by the AGR.
+
+ +AGRs may respond with one or more FlexOffers. +Where an AGR responds with multiple FlexOffers, the DSO can freely choose the most appropriate offer(s). +Provided the flexibility has not been ordered via a FlexOrder, a FlexOffer may be revoked by the AGR (FlexOfferRevocation). + +Alternatively, if there is an existing agreement between the DSO and AGR, the DSO can procure the flexibility by directly placing a _FlexOrder_, without sending a _FlexRequest_ first: + +
+ ![Direct FlexOrder without FlexRequest](../diagrams/../diagrams/validate-phase-direct-flexorder.puml){ .no-lightbox } +
If there is an existing agreement, DSO can procure flexibility by sending a FlexOrder directly, without FlexRequest
+
+ +Flexibility trading may go on until gate closure time: + +
+ ![Flexibility trading may go on until gate closure time](../diagrams/../diagrams/validate-phase-gate-closure-time.puml){ .no-lightbox } +
Flexibility trading may go on until gate closure time. This includes iterations between plan phase and validate phase. The last accepted D-prognosis before gate closure time serves as a basis for the next phase. Any open FlexOffers, which are not expired, may be ordered after gate closure.
+
+ +## Exchange of D-prognoses between AGR and DSO + +When using D-prognoses as the baseline methodology, an AGR sends its D-prognosis per congestion point to the DSO. +The DSO assesses the validity of each received D-prognosis and informs the AGR whether or not it is accepted. +As long as the gate closure time has not passed, the AGR can update its D-prognoses and resend it to the DSO. +During these iterations, an accepted D-prognosis[^5] is assumed actual, provided no associated updates are received and accepted by the DSO. + +For the exchange of D-Prognoses, USEF specifies the following: + +- An AGR is obliged to create a D-prognosis for its connections as soon as its connection point is declared by a DSO. +The AGR is informed of this congestion point via the mandatory (daily) CRO queries. +- The D-prognosis only includes the forecasted load of those prosumers served by the AGR and that have a connection related to a congestion point. +- The D-Prognosis contains one full calendar day for the day-ahead process. +In the intraday process, all remaining ISPs for that calendar day must be included +- The average power is given per ISP as a minimum time granularity +- The D-Prognosis does not include additional information; e.g. details about the available flexibility or prices + +!!! success "USEF provides the following recommended practices for the exchange of D-Prognoses:" + + - The D-Prognosis is sent day-ahead to the DSO; at the latest, two hours before the gate closure of the national balancing regime (day-ahead gate closure)[^6] + - The DSO can perform a monthly evaluation of the accuracy and reliability of D-prognoses in order to motivate AGRs to improve the D-prognoses they supply + +[^5]: The accepted D-prognosis is the D-prognosis that used as a basis for the next period (Intraday) or phase (operate). +[^6]: For the difference between day-ahead and intraday, please refer to [Iterations between the plan and validate phases](validate-phase.md#iterations-between-the-plan-and-validate-phases) + +## Processing D-prognoses + +When all D-prognoses relating to a particular congestion point are received, the DSO creates a total prognosis for each congestion point. +When accumulating the D-prognoses, the DSO must estimate and add the distribution requirements required for those connections which are not served by an AGR, and, therefore, not included in the D-prognoses. +Using the accumulated D-prognosis, the DSO can determine whether it is possible to distribute the planned energy, or whether the limits of the distribution grid will be reached. + +The timing of the FlexRequest is determined by the DSO, who must make a trade-off between waiting for all AGRs to send their D-prognoses[^7] before identifying grid constraints or issuing a FlexRequest based on its own grid forecasting process. +It is the DSO’s responsibility to combine the two sources of information. +Where alternative baseline methods are used, the DSO will issue a FlexRequest based solely on its own information. + +[^7]: + USEF 2015 specified that the DSO should wait for all D-prognoses to be submitted. + This would allow for a more precise determination of possible congestion and also ensure a fair process of offering and procuring flexibility. + However, this constraint hinders the process in situations where there are missing or late D-prognoses. + +The grid safety analysis can lead to either of the following conclusions: + +- That no congestion is expected. All power flows are within calculated safety margins. +- That congestion is expected as the energy flows exceed calculated safety margins. The DSO then starts the process of acquiring flexibility from the market. + +Where no AGRs are active at the congestion point, there is no market to supply the DSO with flexibility to reduce its energy flows to levels below the safety margins. +In this situation, the system moves to the orange regime. +The resulting DSO processes are outside the scope of this document. +See [^B4] for a global description. + +## Flexibility trading between the AGR and DSO + +If the outcome of the grid safety analysis is that congestion will arise, the system is moved to the yellow regime and the DSO will need to take action. +In order to solve the expected congestion, the following steps are taken: + +1. The DSO requests all AGRs at the congestion point to provide flexibility. +In its request, the DSO indicates the magnitude (amount of excess power) and timing (ISP) of the expected congestion and (optionally) how much capacity is available in the remaining ISPs +2. The AGRs receive the flexibility request for adjusting[^8] distribution requirements +3. AGRs generate offers for the flexibility. Note that these offers could either be the result of a voluntary offering process or compulsory, where there are prearranged bilateral contracts between DSO and AGR (FlexOptions) +4. The DSO receives the flexibility offers +5. The DSO procures flexibility to resolve the congestion issues by placing flexibility orders. +6. The DSO determines whether the expected congestion is solved using the ordered flexibility. +If this is not the case, the system moves to the orange regime (see [^B4] for more details) +7. The AGRs receive the flexibility orders which result in the actual procurement of flexibility by the DSO. +8. AGRs provide an (updated) D-prognosis, incorporating the ordered flexibility. +This step only applies when D-prognoses are used as baseline methodology. + + + +[^B4]: USEF Foundation, "USEF: The Framework Explained," USEF Foundation, Arnhem, 2015. + +[^8]: Either by decreasing energy use, increasing local generation, or time-shifting load. + +When trading via a market platform AGRs typically offer their flexibility without an underlying request (unsolicited flex offers) and the DSO selects appropriate offers. +Steps 1 and 2 are not applicable in this situation. + +- Information about expected congestion is provided to all registered AGRs; +- Expected congestion information includes the direction of the overload (production/consumption); +- Expected congestion information includes the amount of reduction needed; +- Expected congestion information includes available grid capacity for other ISPs. + +See [Rationale for information exchange in flexibility request](../appendix/rationale-for-information-exchange-in-flexibility-request.md) for more details about this information exchange including rationale. + +In the [FlexRequest messages](../message-descriptions/message-catalog/flex-request.md), there is no single power value, rather a power space for each ISP, bound by two power values (“MinPower” and “MaxPower”). +In addition, there is a distinction between ISPs with a ‘requested’ disposition – meaning that there is a request for a deviation on the power consumption/production – and ISPs with an ‘available’ disposition – meaning that there is available space to deviate on the power consumption/production. + +
+ ![Example forecast for a Congestion point, leading to an example FlexRequest, both displayed in graphs](../assets/images/image13.svg.png){ width=1000px } +
Example forecast for a Congestion point, leading to an example FlexRequest, both displayed in graphs
+
+ +In the example used in the figure above, congestion is expected at ISP 2 at a certain congestion point. +The FlexRequest is transmitted to all AGRs that have prosumers on the congestion point, requesting a decrease of consumption (or an increase of production) on ISP 2. +If AGRs choose to shift consumption from ISP 2 to another ISP, the available spaces in the ISPs from the FlexRequest indicate that there is more room for consumption in ISP 5 than in ISP 1, 3 and 4. +A flexibility offer with a consumption shift to ISP 5 is therefore more likely to be ordered. + +Note that a request is always relative to the agreed baseline. +The essence of broadcasting the same request to all AGRs is that the requested deviation is the same for each AGR, relative to its own baseline. +Decreasing power consumption is thereby equivalent to increasing power production and vice versa. + +The distribution of the FlexRequest message is limited to AGRs which are registered via the CRO (see [Plan phase](plan-phase.md)). +The information on direction, amount and available capacity is provided in specific data structures that are part of the FlexRequest message (see [Power](../message-descriptions/message-catalog/power.md)). + +For the procurement of flexibility by the DSOs, USEF specifies the following rules: + +- A flexibility offer is valid until it expires or is revoked. +It is the AGRs responsibility to determine the acceptance deadline. +Revocation is not possible after the offer has been ordered. +- A flexibility order is definite and binding once it has been placed. +- The DSO chooses which flexibility offers it accepts to solve the congestion. +In this regard, it is not obligatory for the DSO to start with the offer that has the lowest price. +The DSO has the freedom to assess the balance between the price and quality[^9] of the flexibility offered in both long-term contracts and short-term offers. +- Bidding takes place at congestion point level, making every congestion point a local flexibility market. +- The DSO sends a flexibility request when the result of the grid safety analysis indicates possible congestion. +- A flexibility order is linked to a flexibility offer and a baseline for settlement purposes. + +[^9]: For example, it is desirable for the DSO to procure flexibility that moves energy use from a moment in time of high load to a moment in time of very low load, rather than procuring flexibility that moves energy use from a moment in of high load to a moment in time at which the maximum of the distribution capacity is almost reached. + +UFTP has two optional structures in the trading messages: + +- [optional] A FlexOffer can contain multiple mutually exclusive options. +The DSO is able to pick one of the options in its FlexOrder. +Whether or not an AGR is allowed to add multiple options is signaled in the CRO. + +- [optional] AGRs may indicate the capability for partial activation in their offers. +In all messages, a minimum activation percentage is provided i.e. all values lower than 100% mean that partial activation is possible. +The DSO could use partial activation to better match the requested flexibility with available offers. +Partial activation applies to all ISPs in the offer and also to the offered price. +For example, if the DSO procures 80% of the offer, all ISPs in the FlexOrder should be 80% of the corresponding ISPs in the FlexOffer, and the settlement price is set to 80% of the original price in the offer. +If the DSO has not implemented the option, it may simply ignore the structure. + +### Updates after flex has been ordered + +USEF specifies that when ISPs are altered as a result of a flexibility deal, the resulting load for these ISPs is used for settlement. +This means that deviation on ISPs with ‘requested’ disposition that have been traded, might lead to penalties for the associated AGR. +Updates on other ISPs are always possible for the AGR but will require a new D-prognosis. +Other AGRs can still change their D-prognoses for all ISPs without incurring a penalty. +More details about the penalty calculation can be found in the [settlement](settle-phase.md). + +The load profile resulting from a flexibility deal will be stored independently from any subsequent updates of the D-prognosis, because it allows the DSO to verify the actual delivery of the flexibility for settlement purposes. + +!!! success "Recommended Practice for flexibility trading:" + + For the procurement of flexibility by the DSOs, USEF recommends the following: + + - Publishing is in an anonymized way + - Pay-as-bid is used for pay-out. + - Timing of the flexibility orders is between 24 and 2 hours before delivery (day-ahead trading). + +## Iterations between the plan and validate phases + +As a result of flexibility exchange with the DSO, the AGRs portfolio is not balanced and so it may wish to re-optimize it. +By doing so, the MCM returns to the [plan phase](plan-phase.md), the only difference being that the AGR now takes the flexibility it has already sold into account. +In addition, during the plan phase, the AGR has the freedom to continuously re-optimize its portfolio whenever deemed necessary (e.g. when new and improved forecasts are available). +The rationale behind this high degree of freedom for the AGRs is to ensure that the flexibility they offer is applied in the most optimal and cost-effective way (i.e. flexibility is used there where it creates most value). + +However, these iterative processes also lead to the issue that D-prognoses change continuously, and continuous alignment is required between AGR/DSO. +As a result, there is a risk that the iterative process between the plan and validate phases does not converge. +In conclusion, there is a balance to be struck between making sure that the iterative processes converge, and offering a high degree of freedom to ensure that the available flexibility is used in the most optimal and cost-effective way. + +### Gate closure times + +For reasons mentioned above, USEF specifies that there needs to be at least two moments in time when the iterations are forced to end. This moment is called the gate closure time. + +In alignment with the current practices in liberalized energy markets, the two gate closure times are: + +1. Day-ahead closure time: the moment at which the day-ahead market closes. +During the day-ahead period, the plan and validate phases can be iterated as often as needed, as long as the system converges before the gate closure time. +After the day-ahead closure time, the processes in the plan phase can only be restarted during the intraday period. + +2. Intraday closure time[^10]: the moment at which the intraday market closes. +During the intraday period, the plan and validate phases can be iterated as often as needed, as long as the system converges before the gate closure time. +After the intraday closure time, the processes in the plan phase cannot be restarted at all, as the MCM moves to the operate phase. + +[^10]: Note that intraday flexibility trading is optional in UFTP so intraday gate closure applies only when intraday trading is enabled by the DSO + +
+ ![Example of USEF day-ahead gate closure time.](../assets/images/image14.emf.odg.svg.png){ width=1000px } +
Example of USEF day-ahead gate closure time.
+
+ +An example of the day-ahead gate closure is given in the figure above. +Please note that while there is a single day-ahead gate closure time per day, there will be multiple intra-day gate closures. +This is illustrated in the figure below. +The ISP corresponding to the current time is in operate phase and ISP’s more than one hour ahead are still in plan or validate phase. + +
+ ![Example of USEF intra-day gate closure times.](../assets/images/image15.emf.odg.svg.png){ width=1000px } +
Example of USEF intra-day gate closure times.
+
+ +!!! success "Recommended Practice:" + + The national regulator determines the specific timing details of the gate closures. USEF recommends: + + - A day-ahead gate closure time of 2 hours before the gate closure of the national balancing market + - An intraday gate closure time of one hour before the start of the ISP + +## Balance responsibility and redispatch options + +The procurement of flexibility by the DSO may impact the AGRs balance position (nomination)[^11]. +Therefore, USEF’s validate phase is iterative with the plan phase, i.e. the AGR can make adjustments to its nomination via energy exchange with its associated BRP and/or energy trades on the energy markets. +When the gate closure time is reached, all issues need to be resolved or there will be in an imbalance in the AGRs portfolio (which is the AGRs responsibility). + +[^11]: his is not the case when the AGR can manage the deviation itself, e.g. one prosumer uses more energy, another prosumer uses less energy, and these two level each other out. + +As an alternative, the procurement of flexibility is organized as an energy trade between AGR and DSO. +In this situation, the AGR portfolio stays balanced and there is no need to iterate to the plan phase. +Nevertheless, the AGR is free to re-optimize its portfolio at any time, for any reason, which could induce iterations. +The DSO faces imbalance as a result of the trade and is responsible for this. +The DSO’s imbalance can be restored via a counter trade outside the congested area (redispatch). + +USEF supports both ways of balance responsibility. +The DSO determines the method of trading for a given congestion point and signals this via the CRO. See [DSOPortfolioUpdate](../message-descriptions/message-catalog/dso-portfolio-update.md). + +!!! success "Recommended practices for balance responsibility:" + - USEF recommends that the AGR retains balance responsibility for day-ahead flexibility trading. + Any imbalance risk as a result of DSO trades can be mitigated via day-ahead energy trades. + - USEF recommends shifting the balance responsibility to the DSO for intraday flexibility trading. + This is equivalent to an energy trade from AGR to DSO. + In order to neutralize its position, the DSO should then trigger a counter-trade (redispatch). diff --git a/specifications/development/docs/index.md b/specifications/development/docs/index.md new file mode 100644 index 00000000..8516ac6f --- /dev/null +++ b/specifications/development/docs/index.md @@ -0,0 +1,24 @@ + + +# USEF Flex Trading Protocol + +The Universal Smart Energy Framework (USEF) has been developed to drive a fast, fair and lowest cost route to an integrated smart energy future. +By delivering one common standard, it enables cost-efficient connectivity of all smart energy projects and technologies. +Its market structure, roles, rules and tools for the commoditization and trading of flexible energy usage work with existing energy markets. + +The USEF Flex Trading protocol (UFTP) is a subset of the USEF framework. +Focused specifically on the exchange of flexibility between Aggregators (AGRs) and DSOs, it describes the corresponding market interactions between them to resolve grid constraints by applying congestion management or grid-capacity management. +UFTP can be used as a stand-alone protocol for flexibility forecasting, offering, ordering, and settlement processes. + +UFTP and the USEF Framework were originally developed, maintained and audited by the USEF Foundation. +In 2021, USEF moved to the Linux Foundation Energy, and the project is rebranded as ‘Shapeshifter – a universal flex trading protocol’. + +## Intellectual property disclaimer + +This specification is provided to you "as is" with no warranties whatsoever, including any warranty of merchantability, non-infringement, or fitness for any particular purpose. +The authors of this specification disclaim all liability, including liability for infringement of any proprietary rights, relating to use or implementation of information in this specification. +The provision of this specification to you does not provide you with any license, express or implied, by estoppel or otherwise, to any intellectual property rights. diff --git a/specifications/development/docs/message-descriptions/message-catalog/agr-portfolio-query-response.md b/specifications/development/docs/message-descriptions/message-catalog/agr-portfolio-query-response.md new file mode 100644 index 00000000..579c41b5 --- /dev/null +++ b/specifications/development/docs/message-descriptions/message-catalog/agr-portfolio-query-response.md @@ -0,0 +1,57 @@ + + +# AGRPortfolioQueryResponse + +Upon receiving and processing an AGRPortfolioQuery message, the receiving implementation must reply with an AGRPortfolioUpdate, indicating whether the query was handled successfully. + +``` + + /> + + /> + /> + /> +/> +``` + +| | | +|----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see section [metadata attributes](metadata-attributes.md). | +| ReferenceMessageID | MessageID of the AGRPortfolioQuery message | +| Result | Indication whether the AGRPortfolioQuery was accepted or rejected. | +| RejectionReason | In case the AGRPortfolioQuery was rejected, this attribute must contain a human-readable description of the reason. | +| Period | The Period that the portfolio is valid. | +| DSO-View | | +| ⇥ DSO-Portfolio | Portfolio of a single DSO that shares connections with the AGR | +| ⇥ ⇥ DSO-Domain | The InternetDomain of the DSO the portfolio applied to. | +| ⇥ ⇥ CongestionPoint | A CongestionPoint that contains at least one Connection of a prosumer that is represented by the AGR. | +| ⇥ ⇥ ⇥ EntityAddress | Entity Address of the CongestionPoint entity being updated. | +| ⇥ ⇥ ⇥ MutexOffersSupported | Indicates whether the DSO accepts mutual exclusive FlexOffers on this CongestionPoint | +| ⇥ ⇥ ⇥ DayAheadRedispatchBy | Indicates which party is responsible for day-ahead redispatch, AGR or DSO. | +| ⇥ ⇥ ⇥ IntradayRedispatchBy | Indicates which party is responsible for intraday ahead redispatch, AGR or DSO. If not specified, there will be no intraday trading on this CongestionPoint. | +| ⇥ ⇥ ⇥ Connection | | +| ⇥ ⇥ ⇥ ⇥ EntityAddress | Entity Address of a Connection that is part of this CongestionPoint. | +| ⇥ ⇥ Connection | Connection not belonging to any DSO CongestionPoint | +| ⇥ ⇥ ⇥ EntityAddress | Entity Address of the Connection | diff --git a/specifications/development/docs/message-descriptions/message-catalog/agr-portfolio-query.md b/specifications/development/docs/message-descriptions/message-catalog/agr-portfolio-query.md new file mode 100644 index 00000000..a88c0ac2 --- /dev/null +++ b/specifications/development/docs/message-descriptions/message-catalog/agr-portfolio-query.md @@ -0,0 +1,21 @@ + + +# AGRPortfolioQuery + +The AGRPortfolioQuery is used by the AGR to retrieve additional information on the connections. + +``` + +``` + +| | | +|----------|--------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see section [metadata attributes](metadata-attributes.md). | +| Period | The Period for which the AGR requests the portfolio information. | diff --git a/specifications/development/docs/message-descriptions/message-catalog/agr-portfolio-update-response.md b/specifications/development/docs/message-descriptions/message-catalog/agr-portfolio-update-response.md new file mode 100644 index 00000000..80577a16 --- /dev/null +++ b/specifications/development/docs/message-descriptions/message-catalog/agr-portfolio-update-response.md @@ -0,0 +1,25 @@ + + +# AGRPortfolioUpdateResponse + +Upon receiving and processing an AGRPortfolioUpdate message, the receiving implementation must reply with an AGRPortfolioUpdateResponse, indicating whether the update was handled successfully. + +``` + +``` + +| | | +|--------------------|----------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| ReferenceMessageID | MessageID of the AGRPortfolioUpdate message | +| Result | Indication whether the AGRPortfolioUpdate was accepted or rejected. | +| RejectionReason | In case the AGRPortfolioUpdate was rejected, this attribute must contain a human-readable description of the reason. | diff --git a/specifications/development/docs/message-descriptions/message-catalog/agr-portfolio-update.md b/specifications/development/docs/message-descriptions/message-catalog/agr-portfolio-update.md new file mode 100644 index 00000000..1a7689d9 --- /dev/null +++ b/specifications/development/docs/message-descriptions/message-catalog/agr-portfolio-update.md @@ -0,0 +1,28 @@ + + +# AGRPortfolioUpdate + +The AGRPortfolioUpdate is used by the AGR to indicate on which Connections it represents prosumers. + +``` + +/> +``` + +| | | +|-----------------|------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| Connection | | +| ⇥ EntityAddress | EntityAddress of the Connection entity being updated. | +| ⇥ StartPeriod | The first Period hat the AGR represents the prosumer at this Connection. | +| ⇥ EndPeriod | The last Period that the AGR represents the prosumer at this Connection, if applicable. | diff --git a/specifications/development/docs/message-descriptions/message-catalog/d-prognosis-response.md b/specifications/development/docs/message-descriptions/message-catalog/d-prognosis-response.md new file mode 100644 index 00000000..0760b4ea --- /dev/null +++ b/specifications/development/docs/message-descriptions/message-catalog/d-prognosis-response.md @@ -0,0 +1,33 @@ + + +# D-PrognosisResponse + +Upon receiving and processing a prognosis message, the receiving implementation must reply with a D-PrognosisResponse, indicating whether the prognosis was syntactically and semantically valid, and, where any FlexOrder messages have previously been sent for any ISP in the period the prognosis applies to, a FlexOrderStatus indication for each of those orders. + +``` + +/> +``` + +| | | +|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| ReferenceMessageID | Reference to the the D-prognosis that was accepted or rejected | +| Result | Indication whether the prognosis was accepted or rejected. A receiving implementation may reject a prognosis if it's syntactically invalid, uses a ISP duration or time zone that deviates from what is agreed upon for the market, is for a unknown Congestion Point or from an AGR that is not listed in the Common Reference, does not contain a full list of ISPs for the Period it applies to, contains implausible power values, applies to a Period for which all ISPs are already pending settlement, or if a Prognosis of the same type and from the same originator with a higher sequence number was already processed previously. | +| RejectionReason | In case the update was rejected, this attribute must contain a human-readable description of the failure. | +| FlexOrderStatus | Status of a previously submitted FlexOrder | +| ⇥ Sequence | Sequence of the previously submitted FlexOrder. | +| ⇥ IsValidated | Indication whether the Prognosis that was just received reflects this previously submitted FlexOrder. | + diff --git a/specifications/development/docs/message-descriptions/message-catalog/d-prognosis.md b/specifications/development/docs/message-descriptions/message-catalog/d-prognosis.md new file mode 100644 index 00000000..159a443d --- /dev/null +++ b/specifications/development/docs/message-descriptions/message-catalog/d-prognosis.md @@ -0,0 +1,38 @@ + + +# D-Prognosis + +D-Prognosis messages are used to communicate D-prognoses between AGRs and DSOs. +D-Prognosis messages always contain data for all ISPs for the period they apply to, even if a prognosis is sent after the start of the period, when one or more ISPs are already in the operate or settlement phase. +Receiving implementations should ignore the information supplied for those ISPs. + +``` + +/> +``` + +| | | +|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| Period | The Period this D-Prognosis applies to. | +| CongestionPoint | Entity Address of the Congestion Point this prognosis applies to. Required for D-prognoses, prohibited for other prognosis types. | +| Revision | Revision of this message. A sequence number that must be incremented each time a new revision of a prognosis is sent. The combination of SenderDomain and PrognosisSequence should be unique. | +| ISP | | +| ⇥ Power | Power specified for this ISP in Watts. Also see the important notes about the sign of this attribute in the main documentation entry for the Power attribute. | +| ⇥ Start | Number of the first ISP this element refers to. The first ISP of a day has number 1. | +| ⇥ Duration | The number of the ISPs this element represents. | + +Note: Every day-ahead D-Prognosis must contain a Power value for every single ISP of the specified Period. diff --git a/specifications/development/docs/message-descriptions/message-catalog/dso-portfolio-query-response.md b/specifications/development/docs/message-descriptions/message-catalog/dso-portfolio-query-response.md new file mode 100644 index 00000000..0fa4fd65 --- /dev/null +++ b/specifications/development/docs/message-descriptions/message-catalog/dso-portfolio-query-response.md @@ -0,0 +1,40 @@ + + +# DSOPortfolioQueryResponse + +Upon receiving and processing a DSOPortfolioQuery message, the receiving implementation must reply with a DSOPortfolioQueryResponse, indicating whether the query executed successfully, and if it did, including the query results. +Most queries will return zero or more congestion points + +``` + + /> +/> +``` + +| | | +|--------------------|-----------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| ReferenceMessageID | MessageID of the DSOPortfolioQuery message | +| Result | Indication whether the query was executed successfully or failed. | +| RejectionReason | In case the query failed, this attribute must contain a human-readable description of the failure reason. | +| Period | The period that was queried. This is also the Period for which the portfolio is valid. | +| CongestionPoint | The congestion point that was queried. | +| ⇥ EntityAddress | The entity address of the congestion point. | +| ⇥ Connection | A Connection that is part of the congestion point. | +| ⇥ ⇥ EntityAddress | The entity address of the Connection | +| ⇥ ⇥ AGR-Domain | The internet domain of the AGR that represents the prosumer connected on this Connection, if applicable. | diff --git a/specifications/development/docs/message-descriptions/message-catalog/dso-portfolio-query.md b/specifications/development/docs/message-descriptions/message-catalog/dso-portfolio-query.md new file mode 100644 index 00000000..d21adddb --- /dev/null +++ b/specifications/development/docs/message-descriptions/message-catalog/dso-portfolio-query.md @@ -0,0 +1,23 @@ + + +# DSOPortfolioQuery + +DSOPortfolioQuery is used by DSOs to discover which AGRs represent connections on its registered congestion point(s). + +``` + +``` + +| | | +|---------------|------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| EntityAddress | Entity Address of the CongestionPoint entity being queried. | +| Period | The Period being queried. | diff --git a/specifications/development/docs/message-descriptions/message-catalog/dso-portfolio-update-response.md b/specifications/development/docs/message-descriptions/message-catalog/dso-portfolio-update-response.md new file mode 100644 index 00000000..1033fa95 --- /dev/null +++ b/specifications/development/docs/message-descriptions/message-catalog/dso-portfolio-update-response.md @@ -0,0 +1,25 @@ + + +# DSOPortfolioUpdateResponse + +Upon receiving and processing a DSOPortfolioUpdate message, the receiving implementation must reply with a DSOPortfolioUpdateResponse, indicating whether the update was handled successfully. + +``` + +``` + +| | | +|--------------------|----------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| ReferenceMessageID | MessageID of the DSOPortfolioUpdate message | +| Result | Indication whether the DSOPortfolioUpdate was accepted or rejected. | +| RejectionReason | In case the DSOPortfolioUpdate was rejected, this attribute must contain a human-readable description of the reason. | diff --git a/specifications/development/docs/message-descriptions/message-catalog/dso-portfolio-update.md b/specifications/development/docs/message-descriptions/message-catalog/dso-portfolio-update.md new file mode 100644 index 00000000..d0d9ee64 --- /dev/null +++ b/specifications/development/docs/message-descriptions/message-catalog/dso-portfolio-update.md @@ -0,0 +1,43 @@ + + +# DSOPortfolioUpdate + +The DSOPortfolioUpdate is used by the DSO to indicate on which congestion points it wants to engage in flexibility trading. + +``` + + /> +/> +``` + +| | | +|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| CongestionPoint | | +| ⇥ EntityAddress | Entity Address of the CongestionPoint entity being updated. | +| ⇥ StartPeriod | The first Period that the DSO is trading on this CongestionPoint. | +| ⇥ EndPeriod | The last Period that the DSO is trading on this CongestionPoint. | +| ⇥ MutexOffersSupported | Indicates whether the DSO accepts mutual exclusive FlexOffers on this CongestionPoint | +| ⇥ DayAheadRedispatchBy | Indicates which party is responsible for day-ahead redispatch, AGR or DSO. | +| ⇥ IntradayRedispatchBy | Indicates which party is responsible for intraday ahead redispatch, AGR or DSO. If not specified, there will be no intraday trading on this CongestionPoint. | +| ⇥ Connection | | +| ⇥ ⇥ EntityAddress | Entity Address of a Connection that is part of this CongestionPoint. | +| ⇥ ⇥ StartPeriod | The first Period that the Connection is part of this CongestionPoint. Notes:
  • The StartPeriod of a Connection should be greater than or equal to the StartPeriod of the CongestionPoint.
  • The StartPeriod of a Connection should be smaller than or equal to the EndPeriod of the CongestionPoint.
  • CRO implementors may choose to explicitly check for this and reject updates that do not comply.
| +| ⇥ ⇥ EndPeriod | The last Period that the Connection is part of this CongestionPoint. Notes:
  • The EndPeriod of a Connection should be null if and only if the EndPeriod of the CongestionPoint is null.
    The EndPeriod of a Connection should be greater than or equal to the StartPeriod of the CongestionPoint.
  • The EndPeriod of a Connection should be smaller than or equal to the EndPeriod of the CongestionPoint.
  • CRO implementors may choose to explicitly check for this and reject updates that do not comply.
| diff --git a/specifications/development/docs/message-descriptions/message-catalog/flex-offer-response.md b/specifications/development/docs/message-descriptions/message-catalog/flex-offer-response.md new file mode 100644 index 00000000..37c165f0 --- /dev/null +++ b/specifications/development/docs/message-descriptions/message-catalog/flex-offer-response.md @@ -0,0 +1,25 @@ + + +# FlexOfferResponse + +Upon receiving and processing a FlexOffer message, the receiving implementation must reply with a FlexOfferResponse, indicating whether the flexibility offer was processed successfully. + +``` + +``` + +| | | +|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| ReferenceMessageID | MessageID of the FlexOffer that has been accepted or rejected. | +| Result | Indication whether the flex offer was accepted or rejected. Rejection is allowed in case no matching FlexRequest can be found, or the FlexOffer does not contain a valid price for each ISP with Disposition=Requested in the corresponding FlexRequest. | +| RejectionReason | In case the offer was rejected, this attribute must contain a human-readable description of the reason. | diff --git a/specifications/development/docs/message-descriptions/message-catalog/flex-offer-revocation-response.md b/specifications/development/docs/message-descriptions/message-catalog/flex-offer-revocation-response.md new file mode 100644 index 00000000..c1ec0b24 --- /dev/null +++ b/specifications/development/docs/message-descriptions/message-catalog/flex-offer-revocation-response.md @@ -0,0 +1,25 @@ + + +# FlexOfferRevocationResponse + +Upon receiving and processing a FlexOfferRevocation message, the receiving implementation must reply with a FlexOfferRevocationResponse, indicating whether the revocation was handled successfully. + +``` + +``` + +| | | +|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| ReferenceMessageID | MessageID of the FlexOfferRevocation that has been accepted or rejected. | +| Result | Indication whether the revocation was accepted or rejected. Rejection is allowed in case the FlexOffer is unknown (it is the responsibility of the sending party not to revoke FlexOffer messages that have not yet been accepted), or the offered flexibility has already been ordered. | +| RejectionReason | In case the revocation was rejected, this attribute must contain a human-readable description of the reason. | diff --git a/specifications/development/docs/message-descriptions/message-catalog/flex-offer-revocation.md b/specifications/development/docs/message-descriptions/message-catalog/flex-offer-revocation.md new file mode 100644 index 00000000..88d17ad4 --- /dev/null +++ b/specifications/development/docs/message-descriptions/message-catalog/flex-offer-revocation.md @@ -0,0 +1,23 @@ + + +# FlexOfferRevocation + +The FlexOfferRevocation message is used by the AGR to revoke a FlexOffer previously sent to a DSO. +It voids the FlexOffer, even if its validity time has not yet expired. +Revocation is not allowed for FlexOffers that already have associated accepted FlexOrders. + +``` + +``` + +| | | +|--------------------|--------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| FlexOfferMessageID | MessageID of the FlexOffer message that is being revoked: this FlexOffer must have been accepted previously. | diff --git a/specifications/development/docs/message-descriptions/message-catalog/flex-offer.md b/specifications/development/docs/message-descriptions/message-catalog/flex-offer.md new file mode 100644 index 00000000..e74359f8 --- /dev/null +++ b/specifications/development/docs/message-descriptions/message-catalog/flex-offer.md @@ -0,0 +1,62 @@ + + +# FlexOffer + +FlexOffer messages are used by AGRs to make DSOs an offer for provision of flexibility. +A FlexOffer message contains a list of ISPs and, for each ISP, the change in consumption or production offered and the price for the total amount of flexibility offered. +FlexOffer messages can be sent once a FlexRequest message has been received but can also be sent unsolicited. +Note that multiple FlexOffer messages may be sent based on a single FlexRequest, e.g. to increase the chance that the DSO will order at least part of its available flexibility. +The AGR must make sure that it can actually provide the flexibility offered across all of its FlexOffers. + +``` + + /> +/> +``` + +| | | +|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see section [metadata attributes](metadata-attributes.md). | +| Period | The Period the ISPs referenced in this FlexOffer message belong to. | +| CongestionPoint | Entity Address of the Congestion Point this FlexOffer message applies to. | +| ExpirationDateTime | Date and time, including the time zone (ISO 8601 formatted as per [http://www.w3.org/TR/NOTE-datetime](http://www.w3.org/TR/NOTE-datetime)) until when the FlexOffer message is valid. | +| Unsolicited | Indicates whether this FlexOffer is intended to be unsolicited (i.e. without a preceding FlexRequest). | +| FlexRequestMessageID | MessageID of the FlexRequest message this request is based on (mandatory if and only if solicited). | +| ContractID | Reference to the concerning bilateral contract, if applicable. | +| D-PrognosisMessageID | MessageID of the D-Prognosis this request is based on, if it has been agreed that the baseline is based on D-prognoses. | +| BaselineReference | Identification of the baseline prognosis, if another baseline methodology is used than based on D-prognoses. | +| Currency | ISO 4217 code indicating the currency that applies to the price of the FlexOffer. | +| OfferOption | If the DSO does not support mutually exclusive offers it will reject FlexOffers that contain more than one OfferOption. | +| ⇥ OptionReference | The identification of this option | +| ⇥ Price | The asking price for the flexibility offered in this option. | +| ⇥ MinActivationFactor | The minimal activation factor for this OfferOption. If this attribute is omitted, a default value of 1.00 must be assumed.
An AGR may choose to include MinActivationFactor in FlexOffers even if the DSO is not interested in partial activation. In that case the DSO will simply use an ActivationFactor of 1.00 in every FlexOrder. | +| ⇥ ISP | | +| ⇥ ⇥ Disposition | Optional, used only for FlexRequest messages: indication whether the Power specified for this ISP represents available capacity or a request for reduction/increase. | +| ⇥ ⇥ Power | Power specified for this ISP in Watts. Also see the important notes about the sign of this attribute in the main documentation entry for the ISP element, section [power](power.md). | +| ⇥ ⇥ Start | Number of the first ISP this element refers to. The first ISP of a day has number 1. | +| ⇥ ⇥ Duration | The number of the ISPs this element represents. Optional, default value is 1. | + + diff --git a/specifications/development/docs/message-descriptions/message-catalog/flex-order-response.md b/specifications/development/docs/message-descriptions/message-catalog/flex-order-response.md new file mode 100644 index 00000000..9011825b --- /dev/null +++ b/specifications/development/docs/message-descriptions/message-catalog/flex-order-response.md @@ -0,0 +1,25 @@ + + +# FlexOrderResponse + +Upon receiving and processing a FlexOrder message, the receiving implementation must reply with a FlexOrderResponse, indicating whether the update was handled successfully. + +``` + +``` + +| | | +|--------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| ReferenceMessageID | MessageID of the FlexOrder that has just been accepted or rejected. | +| Result | Indication whether the order was accepted or rejected. Rejection is only allowed in case the FlexOrder was already accepted previously, cannot be found, or does not exactly match the contents of the corresponding FlexOffer. | +| RejectionReason | In case the order was rejected, this attribute must contain a human-readable description of the reason. | diff --git a/specifications/development/docs/message-descriptions/message-catalog/flex-order.md b/specifications/development/docs/message-descriptions/message-catalog/flex-order.md new file mode 100644 index 00000000..2464b2ec --- /dev/null +++ b/specifications/development/docs/message-descriptions/message-catalog/flex-order.md @@ -0,0 +1,54 @@ + + +# FlexOrder + +FlexOrder messages are used by DSOs to purchase flexibility from an AGR, either based on a previous FlexOffer or directly. +A FlexOrder message contains a list of ISPs, with, for each ISP, the change in consumption or production to be realized by the AGR, and the accepted price to be paid by the DSO for this amount of flexibility. +This ISP list should be copied from the FlexOffer message (if any) without modification: AGR implementations will (and must) reject FlexOrder messages where the ISP list is not exactly the same as offered. + +``` + +/> +``` + +| | | +|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| Period | Period the ISPs referenced in this FlexOrder message belong to. | +| CongestionPoint | Entity Address of the Congestion Point this FlexOrder message applies to | +| Unsolicited | Indicates whether this FlexOrder is intended to be unsolicited (i.e. without a preceding FlexOffer). | +| FlexOfferMessageID | MessageID of the FlexOffer message this order is based on (mandatory if and only if solicited). | +| ContractID | Reference to the bilateral contract in question, if applicable. | +| D-PrognosisMessageID | MessageID of the D-Prognosis this order is based on, if present. | +| BaselineReference | Identification of the baseline prognosis, if another baseline methodology is used than based on D-prognoses. | +| Price | The price for the flexibility ordered. Usually, the price should match the price of the related FlexOffer. | +| Currency | ISO 4217 code indicating the currency that applies to the price of the FlexOrder. | +| OrderReference | Order number assigned by the DSO originating the FlexOrder. To be stored by the AGR and used in the settlement phase. | +| OptionReference | The OptionReference from the OfferOption chosen from the FlexOffer, if applicable. | +| ActivationFactor | The activation factor for this OfferOption. If this attribute is omitted, a default value of 1.00 must be assumed.
Notes:
The ActivationFactor must be greater than or equal to the MinActivationFactor in the OfferOption chosen from the FlexOffer. | +| ISP | | +| ⇥ Power | Power specified for this ISP in Watts. Also see the important notes about the sign of this attribute in the main documentation entry for the ISP element, section [power](power.md). | +| ⇥ Start | Number of the first ISP this element refers to. The first ISP of a day has number 1. | +| ⇥ Duration | The number of the ISPs this element represents. Optional, default value is 1. | diff --git a/specifications/development/docs/message-descriptions/message-catalog/flex-request-response.md b/specifications/development/docs/message-descriptions/message-catalog/flex-request-response.md new file mode 100644 index 00000000..c97a6b2b --- /dev/null +++ b/specifications/development/docs/message-descriptions/message-catalog/flex-request-response.md @@ -0,0 +1,25 @@ + + +# FlexRequestResponse + +Upon receiving and processing a FlexRequest message, the receiving implementation must reply with a FlexRequestResponse, indicating whether the flexibility request was processed successfully. + +``` + +``` + +| | | +|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| ReferenceMessageID | MessageID of the FlexRequest that has been accepted or rejected. | +| Result | Indication whether the flex request was accepted or rejected. Rejection is allowed in case the FlexRequest is not based on our latest Prognosis, a FlexRequest from the same participant for the indicated period with a higher sequence number was already accepted previously or the FlexRequest does not contain any ISPs with Disposition=Requested. | +| RejectionReason | In case the request was rejected, this attribute must contain a human-readable description of the reason. | diff --git a/specifications/development/docs/message-descriptions/message-catalog/flex-request.md b/specifications/development/docs/message-descriptions/message-catalog/flex-request.md new file mode 100644 index 00000000..9e53a49e --- /dev/null +++ b/specifications/development/docs/message-descriptions/message-catalog/flex-request.md @@ -0,0 +1,45 @@ + + +# FlexRequest + +FlexRequest messages are used by DSOs to request flexibility from AGRs. +In addition to one or more ISP elements with Disposition=Requested, indicating the actual need to reduce consumption or production, the message should also include the remaining ISPs for the current period where Disposition=Available. + +``` + +/> +``` + +| | | +|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| Period | The Period this FlexRequest message applies to. | +| ContractID | Reference to the concerning contract, if applicable. The contract may be either bilateral or commoditized market contract. | +| ServiceType | Service type for this request, the service type determines response characteristics such as latency or asset participation type. Each contract may specify multiple service-types. | +| CongestionPoint | Entity Address of the Congestion Point this FlexRequest message applies to. | +| Revision | Revision of this message, a sequence number that must be incremented each time a new revision of a FlexRequest message is sent. | +| ExpirationDateTime | Date and time, including the time zone (ISO 8601 formatted as per [http://www.w3.org/TR/NOTE-datetime](http://www.w3.org/TR/NOTE-datetime)) until when the FlexRequest message is valid. | +| ISP | | +| ⇥ Disposition | indication whether the Power specified for this ISP represents available capacity or a request for reduction/increase.
At least one ISP should have Disposition = Requested | +| ⇥ MinPower | Lower bound for available/requested space to deviate from the baseline (in Watts).
For further explanation, see section [Flexibility trading between the AGR and DSO](../../general-description/validate-phase.md#flexibility-trading-between-the-agr-and-dso). Also see the important notes about the sign of this attribute in the ISP element, section [power](power.md). | +| ⇥ MaxPower | Upper bound for available/requested space to deviate from the baseline (in Watts).
For further explanation, see section [Flexibility trading between the AGR and DSO](../../general-description/validate-phase.md#flexibility-trading-between-the-agr-and-dso). Also see the important notes about the sign of this attribute in the ISP element, section [power](power.md). | +| ⇥ Start | Number of the first ISP this element refers to. The first ISP of a day has number 1. | +| ⇥ Duration | The number of the ISPs this element represents. Optional, default value is 1. | diff --git a/specifications/development/docs/message-descriptions/message-catalog/flex-reservation-update-response.md b/specifications/development/docs/message-descriptions/message-catalog/flex-reservation-update-response.md new file mode 100644 index 00000000..67dea8f6 --- /dev/null +++ b/specifications/development/docs/message-descriptions/message-catalog/flex-reservation-update-response.md @@ -0,0 +1,25 @@ + + +# FlexReservationUpdateResponse + +Upon receiving and processing a FlexReservationUpdate message, the AGR must reply with a FlexReservationUpdateResponse, indicating whether the FlexReservationUpdate was processed successfully. + +``` + +``` + +| | | +|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see section [metadata attributes](metadata-attributes.md). | +| ReferenceMessageID | MessageID of the concerning FlexReservationUpdate message | +| Result | Indication whether the FlexReservationUpdate was accepted or rejected. Rejection is allowed in case the FlexReservationUpdate does not match the bilateral contract or its agreements or the deadline for sending the update has expired. | +| RejectionReason | In case the request was rejected, this attribute must contain a human-readable description of the reason. | diff --git a/specifications/development/docs/message-descriptions/message-catalog/flex-reservation-update.md b/specifications/development/docs/message-descriptions/message-catalog/flex-reservation-update.md new file mode 100644 index 00000000..10ff9125 --- /dev/null +++ b/specifications/development/docs/message-descriptions/message-catalog/flex-reservation-update.md @@ -0,0 +1,37 @@ + + +# FlexReservationUpdate + +For bilateral contracts, FlexReservationUpdate messages are used by DSOs to signal to an AGR which part of the contracted volume is still reserved and which part is not needed and may be used for other purposes. +For each ISP, a power value is given which indicates how much power is still reserved. Zero power means that no power is reserved for that ISP and the sign of the power indicates the direction. + +``` + +/> +``` + +| | | +|-----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see section [metadata attributes](metadata-attributes.md). | +| Period | The Period this FlexRequest message applies to. | +| CongestionPoint | Entity Address of the Congestion Point this FlexRequest message applies to. | +| ContractID | Reference to the bilateral contract in question. | +| Reference | Message reference, assigned by the DSO originating the FlexReservationUpdate. | +| ISP | | +| ⇥ Power | Remaining reserved power specified for this ISP in Watts. See important notes about the [flex reservation mechanism](../../appendix/flex-reservation-mechanism.md). | +| ⇥ Start | Number of the first ISP this element refers to. The first ISP of a day has number 1. | +| ⇥ Duration | The number of the ISPs this element represents. Optional, default value is 1. | diff --git a/specifications/development/docs/message-descriptions/message-catalog/flex-settlement-response.md b/specifications/development/docs/message-descriptions/message-catalog/flex-settlement-response.md new file mode 100644 index 00000000..336ecaf6 --- /dev/null +++ b/specifications/development/docs/message-descriptions/message-catalog/flex-settlement-response.md @@ -0,0 +1,58 @@ + + +# FlexSettlementResponse + +Upon receiving and processing a FlexSettlement message, the AGR must reply with a FlexSettlementResponse, indicating whether the initial message was handled successfully. +When a FlexSettlement message is rejected, the DSO should consider all FlexOrderSettlement elements of that message related to potential dispute. + +``` + + + /> + /> +/> +``` + +| | | +|---------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| ReferenceMessageID | MessageID of the FlexSettlement that has just been accepted or rejected | +| Result | Indication whether the message was accepted or rejected. Rejection is only allowed in case a FlexSettlement covering a given period was already accepted previously, or contains invalid data. If one or more settlement items included in the message are not in accordance with the AGR’s accounting, the message should still be accepted, and the dispute communicated using the appropriate FlexOrderSettlementStatus elements. | +| RejectionReason | In case the message was rejected, this attribute must contain a human-readable description of the reason. | +| FlexOrderSettlementStatus | Each FlexOrderSettlementStatus element indicates whether the settlement details about a FlexOrder, included in the corresponding FlexOrderSettlement element, are accepted or disputed by the AGR. | +| ⇥ OrderReference | Order reference assigned by the DSO when originating the FlexOrder. | +| ⇥ Disposition | Indication whether the AGR accepts the order settlement details provided by the DSO (and will invoice accordingly), or disputes these details. | +| ⇥ DisputeReason | In case the order settlement was disputed, this attribute must contain a human-readable description of the reason. | +| ContractSettlementStatus | Each ContractSettlementStatus element indicates whether the settlement details about a bilateral contract, included in the corresponding ContractSettlement element, are accepted or disputed by the AGR. | +| ⇥ ContractID | Reference to the concerning bilateral contract. | +| ⇥ Period | List of all periods from the ContractSettlement, including possible lacking periods | +| ⇥ ⇥ Period | Period the settlement status refers to. | +| ⇥ ⇥ ISP | | +| ⇥ ⇥ ⇥ Start | Number of the first ISP this element refers to. The first ISP of a day has number 1. | +| ⇥ ⇥ ⇥ Duration | The number of ISPs this element represents. It is recommended to merge consecutive ISPs with the same disposition. | +| ⇥ ⇥ ⇥ Disposition | Indication whether the AGR accepts the settlement details as provided by the DSO from the ISP(s) in question (and will invoice accordingly), or disputes these details. | +| ⇥ ⇥ ⇥ DisputeReason | In case the settlement from the ISP(s) was disputed, this attribute must contain a human-readable description of the reason. | + +Handling disputed settlement details is a manual process outside the UFTP scope. diff --git a/specifications/development/docs/message-descriptions/message-catalog/flex-settlement.md b/specifications/development/docs/message-descriptions/message-catalog/flex-settlement.md new file mode 100644 index 00000000..6bc7cdcb --- /dev/null +++ b/specifications/development/docs/message-descriptions/message-catalog/flex-settlement.md @@ -0,0 +1,92 @@ + + +# FlexSettlement + +The FlexSettlement message is sent by DSOs on a regular basis (typically monthly) to AGRs, in order to initiate settlement. +It includes a list of all FlexOrders placed by the originating party during the settlement period. + +``` + + /> + + /> + /> +/> +``` + + +| | | +|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| PeriodStart | First Period of the settlement period this message applies to. | +| PeriodEnd | Last Period of the settlement period this message applies to. | +| Currency | ISO 4217 code indicating the currency that applies to all amounts (flex price, penalty and net settlement) in this message. | +| FlexOrderSettlement | | +| ⇥ Period | Period the FlexOrder refers to. | +| ⇥ ContractID | Reference to the concerning bilateral contract, if it is linked to it. | +| ⇥ MessageID | MessageID of the Prognosis message (more specifically: the D-Prognosis) the FlexOrder is based on, if it has been agreed that the baseline is based on D-prognoses. | +| ⇥ BaselineReference | Identification of the baseline prognosis, if another baseline methodology is used than based on D-prognoses. | +| ⇥ OrderReference | Order reference assigned by the DSO when originating the FlexOrder. | +| ⇥ CongestionPoint | Entity Address of the Congestion Point the FlexOrder applies to. | +| ⇥ Price | The price accepted for supplying the ordered amount of flexibility as per the referenced FlexOrder messages. | +| ⇥ Penalty | Optional (default zero) penalty due a non-zero PowerDeficiency. | +| ⇥ NetSettlement | Net settlement amount for this Period: Price minus Penalty | +| ⇥ ISP | | +| ⇥ ⇥ Start | Number of the first ISP this element refers to. The first ISP of a day has number 1. | +| ⇥ ⇥ Duration | The number of ISPs this element represents. Optional, default value is 1. | +| ⇥ ⇥ BaselinePower | Power originally forecast (as per the referenced baseline) for this ISP in Watts. | +| ⇥ ⇥ OrderedFlexPower | Amount of flex power ordered (as per the referenced FlexOrder message) for this ISP in Watts. | +| ⇥ ⇥ ActualPower | Actual amount of power for this ISP in Watts, as measured/determined by the DSO and allocated to the AGR. | +| ⇥ ⇥ DeliveredFlexPower | Actual amount of flex power delivered for this ISP in Watts, as determined by the DSO. | +| ⇥ ⇥ PowerDeficiency | Optional (default zero) amount of flex power sold but not delivered for this ISP in Watts, as determined by the DSO. | +| ContractSettlement | | +| ⇥ ContractID | Reference to the bilateral contract in question. | +| ⇥ Period | List of periods containing reservations | +| ⇥ ⇥ Period | Period the settlement refers to. | +| ⇥ ⇥ ISP | | +| ⇥ ⇥ ⇥ Start | Number of the first ISP this element refers to. The first ISP of a day has number 1. | +| ⇥ ⇥ ⇥ Duration | The number of ISPs this element represents. Optional, default value is 1. | +| ⇥ ⇥ ⇥ ReservedPower | Amount of flex power that has been reserved (and not released using a FlexReservationUpdate message) | +| ⇥ ⇥ ⇥ RequestedPower | Amount of flex power that has been both reserved in advance and has been requested using a FlexRequest (i.e. the lowest amount of flex power for this ISP). If there was no FlexRequest, this field is omitted. | +| ⇥ ⇥ ⇥ AvailablePower | Amount of flex power that is considered available based on the FlexRequest in question.
In case RequestedPower=0, AvailablePower is defined so that the offered power is allowed to be between 0 and AvailablePower in terms of compliancy (see [Flex reservation mechanism](../../appendix/flex-reservation-mechanism.md) for details).
In case RequestedPower ≠0, AvailablePower is defined so that the offered power is allowed to exceed the amount of requested power up to AvailablePower.
If this is relevant for settlement, the DSO can include this field. | +| ⇥ ⇥ ⇥ OfferedPower | Amount of flex power that has been reserved in advance, requested using a FlexRequest and covered in an offer from the AGR. If there was no offer, this field is omitted. If there were multiple offers, only the one is considered that is most compliant (see [Flex reservation mechanism](../../appendix/flex-reservation-mechanism.md) for details about compliancy). | +| ⇥ ⇥ ⇥ OrderedPower | Amount of flex power that has been ordered using a FlexOrder message that was based on a FlexOffer, both linked to this contract. If there was no order, this field is omitted. | diff --git a/specifications/development/docs/message-descriptions/message-catalog/index.md b/specifications/development/docs/message-descriptions/message-catalog/index.md new file mode 100644 index 00000000..09f9a299 --- /dev/null +++ b/specifications/development/docs/message-descriptions/message-catalog/index.md @@ -0,0 +1,13 @@ + + +# Message catalog + +USEF messages consist of XML, use UTF-8 encoding, and should validate against the USEF schema corresponding to the specification version implemented by a participant. +The current version of this schema, as well as historic production versions are available for download from the [Shapeshifter Github](https://github.com/shapeshifter/shapeshifter-specification). +Message types can be differentiated using the name of their root node. + +To allow extensibility as well as forward and backward compatibility of XML messages, the USEF schema allows additional elements in each defined sequence, as long as these elements have an explicit, non-default XML namespace. diff --git a/specifications/development/docs/message-descriptions/message-catalog/metadata-attributes.md b/specifications/development/docs/message-descriptions/message-catalog/metadata-attributes.md new file mode 100644 index 00000000..cd39d6f6 --- /dev/null +++ b/specifications/development/docs/message-descriptions/message-catalog/metadata-attributes.md @@ -0,0 +1,33 @@ + + +# Metadata attributes + +The Metadata attributes contain metadata that are common for each non-wrapper USEF message. + +XML representation summary + +``` +SenderDomain = InternetDomain +RecipientDomain = InternetDomain +TimeStamp = DateTime +MessageID = UUID +ConversationID = UUID +ISP-Duration = Duration +TimeZone = TimezoneName +Version = SpecVersion +``` + +| | | +|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| SenderDomain | The Internet domain of the USEF participant sending this message. When receiving a message, its value should match the value specified in the SignedMessage wrapper: otherwise, the message must be rejected as invalid. When replying to this message, this attribute, combined with the SenderRole, is used to look up the USEF endpoint the reply message should be delivered to. | +| RecipientDomain | Internet domain of the participant this message is intended for. When sending a message this attribute is used to look up the Shapeshifter endpoint the message should be delivered to. | +| TimeStamp | Date and time this message was created, including the time zone (ISO 8601 formatted as per [http://www.w3.org/TR/NOTE-datetime](http://www.w3.org/TR/NOTE-datetime)). | +| MessageID | Unique identifier (UUID/GUID as per IETF RFC 4122) for this message, to be generated when composing each message. | +| ConversationID | Unique identifier (UUID/GUID as per IETF RFC 4122) used to correlate responses with requests, to be generated when composing the first message in a conversation and subsequently copied from the original message to each reply message. | +| ISP-Duration | ISO 8601 time interval (minutes only, for example PT15M) indicating the duration of the ISPs referenced in this message. Although the ISP length is a market-wide fixed value, making this assumption explicit in relevant messages is important for validation purposes, allowing implementations to reject messages with an errant ISP duration.
Only messages that refer to individual ISPs must include this attribute in the metadata. | +| TimeZone | Time zone ID (as per the IANA time zone database, [http://www.iana.org/time-zones](http://www.iana.org/time-zones), for example: Europe/Amsterdam) indicating the UTC offset that applies to the Period referenced in this message. Although the time zone is a market-wide fixed value, making this assumption explicit in relevant messages is important for validation purposes, allowing implementations to reject messages with an errant UTC offset.
Only messages that refer to a specific Period must include this attribute in the metadata. | +| Version | Shapeshifter specification version following semantic versioning rules e.g. 4.0.0 | diff --git a/specifications/development/docs/message-descriptions/message-catalog/metering-response.md b/specifications/development/docs/message-descriptions/message-catalog/metering-response.md new file mode 100644 index 00000000..09e4481f --- /dev/null +++ b/specifications/development/docs/message-descriptions/message-catalog/metering-response.md @@ -0,0 +1,25 @@ + + +# MeteringResponse + +Upon receiving and processing a Metering message, the receiving implementation must reply with a MeteringResponse, indicating whether the update was handled successfully. + +``` + +``` + +| | | +|---------------------|------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see section [metadata attributes](metadata-attributes.md). | +| ReferenceMessageID | MessageID of the Metering message that has just been accepted or rejected. | +| Result | Indication whether the order was accepted or rejected. | +| RejectionReason | In case the metering was rejected, this attribute must contain a human-readable description of the reason. | diff --git a/specifications/development/docs/message-descriptions/message-catalog/metering.md b/specifications/development/docs/message-descriptions/message-catalog/metering.md new file mode 100644 index 00000000..b27a7354 --- /dev/null +++ b/specifications/development/docs/message-descriptions/message-catalog/metering.md @@ -0,0 +1,50 @@ + + +# Metering + +The Metering message is an optional message. +The DSO will specify whether metering messages are required for a given program. +If metering messages are used then the AGR must send metering messages, with one message sent per connection point per day. +The metering messages must all be sent before the settlement can be performed. +It is recommend to send the metering messages daily, once the metering data has been collected for the day. + +``` + + /> +/> +``` + +The profile types to use will be agreed between the DSO and AGR and all agreed profile types must be included. +It is recommended to include the Power profile and in a following major version the Power profile will become a mandatory profile. + +Note: _The power profile represents the average active power during ISP, considering both import and export energy. +Power=(ImportEnergy-ExportEnergy)*(60/ISP-Length-Minutes). +For example with a 15 minute ISP length we have a multiplier of 4, with a 30 minute ISP length we have a multiplier of 2._ + + +| | | +|---------------|---------------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see section [metadata attributes](metadata-attributes.md) | +| Period | The day that the metering data covers | +| EAN | The connection ID which this data refers to | +| Profile | A profile carries a sequence of ISPs with a defined type of metering data | +| ⇥ ProfileType | A value from the ProfileType enum, one of Power, ImportEnergy, ExportEnergy, ImportMeterReading, ExportMeterReading | +| ⇥ Unit | MeteringUnit type, use kW for Power and kWh for energy profile types. | +| ⇥ ISP | | +| ⇥ ⇥ Start | Number of the ISP this element refers to. The first ISP of a day has number 1. | +| ⇥ ⇥ Value | Metering, energy or price value at the end of this ISP, in the designated profile units | diff --git a/specifications/development/docs/message-descriptions/message-catalog/power.md b/specifications/development/docs/message-descriptions/message-catalog/power.md new file mode 100644 index 00000000..ec66669e --- /dev/null +++ b/specifications/development/docs/message-descriptions/message-catalog/power.md @@ -0,0 +1,15 @@ + + +# Power + +Power values occur in many USEF messages. +The sign of a power value is used to distinguish between production and consumption, from the perspective of the prosumer. +A positive value indicates that power flows towards the prosumer (consumption), a negative value indicates flow towards the grid (production). +The following statements are true for ISP elements in all USEF messages: + +- Each ISP in a period may only be addressed once. +- ISP elements may not cross period boundaries. diff --git a/specifications/development/docs/message-descriptions/message-catalog/signed-message.md b/specifications/development/docs/message-descriptions/message-catalog/signed-message.md new file mode 100644 index 00000000..081ea54c --- /dev/null +++ b/specifications/development/docs/message-descriptions/message-catalog/signed-message.md @@ -0,0 +1,26 @@ + + +# SignedMessage + +The SignedMessage element represents the secure wrapper used to submit USEF XML messages from the local message queue to the message queue of a remote participant. +It contains minimal metadata (which is distinct from the common metadata used for all other messages), allowing the recipient to look up the sender's cryptographic scheme and public keys, and the actual XML message, as transformed (signed/sealed) using that cryptographic scheme. + +XML representation summary + +``` + +``` + +| | | +|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| SenderDomain | The Internet domain of the USEF participant sending this message. Upon receiving a message, the recipient should validate that its value matches the corresponding attribute value specified in the inner XML message, once un-sealed: if not, the message must be rejected as invalid.
Domain name matching regular expression `^([a-z0-9]+(-[a-z0-9]+)*\.)+[a-z]{2,}$` | +| SenderRole | The USEF role of the participant sending this message: AGR, CRO or DSO. Receive-time validation should take place as described for the SenderDomain attribute above. The USEF specification identifies additional roles such as BRP and MDC. These are however not in scope of UFTP. | +| Body | The Base-64 encoded inner XML message contained in this wrapper, as transformed (signed/sealed) using the sender's cryptographic scheme. The recipient can determine which scheme applies using a DNS or configuration file lookup, based on the combination of SenderDomain and SenderRole. | diff --git a/specifications/development/docs/message-descriptions/message-catalog/test-message-response.md b/specifications/development/docs/message-descriptions/message-catalog/test-message-response.md new file mode 100644 index 00000000..37e1b566 --- /dev/null +++ b/specifications/development/docs/message-descriptions/message-catalog/test-message-response.md @@ -0,0 +1,26 @@ + + +# TestMessageResponse + +Upon receiving a TestMessage, the receiving implementation must reply with a TestMessageResponse. +Like the TestMessage itself, the TestMessageResponse does not have any content (other than the mandatory metadata). + +``` + +``` + +| | | +|--------------------|---------------------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | +| ReferenceMessageID | MessageID of the TestMessage message that has just been accepted or rejected. | +| Result | Indication whether the TestMessage was accepted or rejected. | +| RejectionReason | In case the TestMessage was rejected, this attribute must contain a human-readable description of the reason. | diff --git a/specifications/development/docs/message-descriptions/message-catalog/test-message.md b/specifications/development/docs/message-descriptions/message-catalog/test-message.md new file mode 100644 index 00000000..7a1cd160 --- /dev/null +++ b/specifications/development/docs/message-descriptions/message-catalog/test-message.md @@ -0,0 +1,21 @@ + + +# TestMessage + +TestMessage does not have any content (other than the mandatory metadata) and may be used by implementations for (connectivity) testing purposes. + +XML representation summary + +``` + +``` + +| | | +|----------|------------------------------------------------------------------------------------------------| +| Metadata | The metadata for this message. For details, see [metadata attributes](metadata-attributes.md). | diff --git a/specifications/development/docs/message-descriptions/scope.md b/specifications/development/docs/message-descriptions/scope.md new file mode 100644 index 00000000..a53d391c --- /dev/null +++ b/specifications/development/docs/message-descriptions/scope.md @@ -0,0 +1,21 @@ + + +# Scope + +USEF defines the content of XML messages between role processes, as required for implementation of USEF’s MCM. +Each message has a unique recipient, identified by the Internet domain and USEF role of the participant. +The message transfer mechanism is responsible for sending and receiving these messages. + +
+ ![Relationship between the normative USEF XML messages (yellow pane) and the best-practice message transfer mechanism (light-blue pane).](../assets/images/image18.emf.odg.svg.png){ width=1000px } +
Relationship between the normative USEF XML messages (yellow pane) and the best-practice message transfer mechanism (light-blue pane).
+
+ +When selecting a message transfer mechanism, local market conditions should be considered and the USEF privacy and security guidelines should be followed [^B5]. +Further recommendations about the message transport mechanism are given in [Message transport mechanism](../appendix/message-transport-mechanism.md). + +[^B5]: USEF Foundation, "USEF: The Privacy and Security Guideline," USEF Foundation, Arnhem, 2015. Available: [https://www.usef.energy/app/uploads/2016/12/USEF_PrivacySecurityGuideline_3nov15.pdf](https://www.usef.energy/app/uploads/2016/12/USEF_PrivacySecurityGuideline_3nov15.pdf) diff --git a/specifications/development/docs/use-case-descriptions/common-concepts.md b/specifications/development/docs/use-case-descriptions/common-concepts.md new file mode 100644 index 00000000..1b1f6a28 --- /dev/null +++ b/specifications/development/docs/use-case-descriptions/common-concepts.md @@ -0,0 +1,26 @@ + + +# Common concepts + +The USEF specification standardizes the logical interfaces and defines the minimum functionality of the components in the form of use cases (this chapter) and [message transport specifications](../appendix/message-transport-mechanism.md) and [message descriptions](../message-descriptions/scope.md). +This leaves room for innovation and possibilities to develop specific implementation architectures based on e.g. size of the market, specific local circumstances or commercial exploitation of USEF platforms. +Stakeholders involved in a USEF market can and must develop business functions and capabilities independently, and focus on their core business and competitive advantage. + +While the USEF specification is technology and implementation agnostic, there are some basic principles to which any USEF implementation architecture must adhere. +Some of these are listed as high-level requirements. +When an ICT implementation architecture is defined, the actual implementation requirements must be defined and included in the design. + +- A USEF market implementation will typically consist of multiple information systems interacting together according to the USEF interaction standard in order to run the market processes. +The USEF foundation does not want to narrow down the open nature of the USEF specifications by defining exactly how the information system architecture must be implemented. +- The USEF specifications do not currently define exceptions and how to handle them. +Therefore, the use cases also prescribe only the default main scenario without error handling, and only the successful outcome. +The single exception to this rule is described in the next bullet. +USEF does provide some recommended practices for handling some of the failure handling. +- Any USEF IT architecture must adhere to the USEF privacy & security guideline.[^B5] +In the USEF use cases the most relevant privacy & security considerations are provided. + +[^B5]: USEF Foundation, "USEF: The Privacy and Security Guideline," USEF Foundation, Arnhem, 2015. Available: [https://www.usef.energy/app/uploads/2016/12/USEF_PrivacySecurityGuideline_3nov15.pdf](https://www.usef.energy/app/uploads/2016/12/USEF_PrivacySecurityGuideline_3nov15.pdf) diff --git a/specifications/development/docs/use-case-descriptions/message-validation.md b/specifications/development/docs/use-case-descriptions/message-validation.md new file mode 100644 index 00000000..9e69c536 --- /dev/null +++ b/specifications/development/docs/use-case-descriptions/message-validation.md @@ -0,0 +1,75 @@ + + +# Message validation + +Incoming messages need to be validated by the recipient for their correctness. +Validation of the semantics is performed by the HTTP over TLS (explained in [Message transport mechanism](../appendix/message-transport-mechanism.md)), but the content still needs to be checked for possible discrepancies. +If the message passes validation, a response message is sent with ‘accepted’ in the result field. +If it fails validation, a response message is sent with ‘rejected’ in the result field, along with a description of the reason why the message is rejected in the RejectionReason field. +Some causes to reject a message are specific for the type of message and are mentioned in the remainder of this chapter. +Other causes are more generic and are listed in the table below. + +This list is not all-encompassing: stakeholders are allowed to formulate other reasonable causes to reject a message, as long as it is clearly explained in the RejectionReason field. Adding the cause of the rejection will facilitate in building a correct implementation. +This field can contain multiple reasons for rejections (separated by a semicolon). + +| RejectionReason | Cause of rejection | Applicable to messages | +|---|---|---| +| Unknown SenderDomain (SignedMessage) | SenderDomain specified in the SignedMessage is unknown to the receiving implementation. | SM | +| Invalid SenderRole | The SenderRole specified in the SignedMessage is invalid. | SM | +| Invalid Sender combination | The combination SenderDomain and SenderRole in the SignedMessage is invalid.| SM | +| Mismatch SenderDomain | SenderDomain specified in the SignedMessage doesn't match with the SenderDomain in the inner XML message. | SM & All other message types | +| Invalid SignedMessage | The SignedMessage complies with the XSD schema, but failed to pass validation. | SM | +| Invalid Message | Despite being schema-compliant, the syntax, type or semantics of the message were unacceptable for the receiving implementation. | All message types | +| Unknown RecipientDomain | The RecipientDomain specified in the inner XML message is not known to the receiving implementation. | All message types | +| Unknown SenderDomain (message) | SenderDomain specified in the message is unknown to the receiving implementation. | All message types except SM | +| Barred Sender | This endpoint is explicitly blocking messages from this sender. | SM | +| Duplicate Identifier | The MessageID attribute of the inner XML message is not unique, and has already been used for a message with different content. This message has been rejected. | All message types except SM | +| Already Submitted | The MessageID attribute of the inner XML message is not unique, but since the message content is the same as that of a previously accepted message, this copy can be considered to be successfully submitted as well. | All message types except SM | +| ISP duration rejected | The message specifies a ISP duration that is not the agreed-upon common value for the market in which it is used. | All message types that contain ISP's: FRU, DP, FR, FO, FOR, M, FS, FS_R| +| TimeZone rejected | The message specifies a TimeZone that has a different UTC offset than is the agreed-upon common value for the market. | All message types that contain Period: APQ, APQ_R, DPQ, DPQ_R, FRU, DP, FR, FO, FOR, M, FS, FS_R | +| Invalid CongestionPoint | Unknown CongestionPoint or the recipient is not active at this CongestionPoint. | FRU, DP, FR, FO, FOR, FS | +| Unknown MessageID reference | The message the MessageID refers to is unknown.
For the referenced MessageType can be filled in.
For example: *FlexRequestMessageID* or *D-PrognosisMessageID*. | APU_R, APQ_R, FRU_R, DP_R, FR_R, FO, FOF_R, FOFR, FOFR_R, FOR, FOR_R, M_R, FS, FS_R | +| Reference Period mismatch | The message the MessageID refers to contains a different Period. | MessageTypes that refer to other messages using MessageID AND contain a Period themselves: APQ_R, FO FOFR, FOR, FS, FS_R | +| Reference message expired | The message MessageID refers to is expired. | APU_R, APQ_R, FRU_R, DP_R, FR_R, FO, FOF_R, FOFR, FOFR_R, FOR, FOR_R, M_R, FS, FS_R | +| Reference message revoked | The message MessageID refers is revoked. | APU_R, APQ_R, FRU_R, DP_R, FR_R, FO, FOF_R, FOFR, FOFR_R, FOR, FOR_R, M_R, FS, FS_R | +| ISPs out of bounds | One or more ISPs are outside the tolerated boundaries.
- At least 1 ISP should exist in the messages that expect them.
- Also, the amount of ISPs that are about a Period (one *day*) can never exceed *(24 hours / ISP-Duration (in hours)) + DST_offset*
What that means is that for example: you can't have more than (24 hours (1 Period) / 0.25 (PT15M)) = 96 ISPss.
Exceptions are depending on wether or not DST applies (for Europe for example), then you have an hour less or more on the day so the maximums would in those cases be: 96 - 4 = 92 or 96 + 4 = 100. More ISPs for that specific Period would be invalid. | FRU, DP, FR, FO, FOR, M, FS, FS_R | +| ISP conflict | One or more ISPs are defined more than once, possibly because of an incorrect duration.
For example:
  

/\>

The second ISP will overlap the first. | FRU, DP, FR, FO, FOR, M, FS, FS_R | +| Period out of bounds | Period of the message is inappropriate.
For example: a FlexRequest with a Period in the past or a settlement item in a FlexSettlement with a Period outside the concerning settlement period. | APQ, APQ_R, DPQ, DPQ_R, FRU, DP, FR, FO, FOR, M, FS, FS_R | +| ExpirationDateTime out of bounds | ExpirationDateTime is in the past or exceeds the ISPs in the message. The acceptable content can best be discussed and agreed upon between the sending and receiving parties. | FR, FOF | +| [Other reasonable cause] | [Implementation specific rejection reason] | TBD | + +Because typing all MessageTypes out in full takes a lot of space, a list of abbreviations has been created that can be used when communicating about the specification: + +| MessageType | Abbreviation | +|---|---| +| SignedMessage | SM | +| TestMessage | TM | +| TestMessageResponse | TM_R | +| AGRPortfolioUpdate | APU | +| AGRPortfolioUpdateResponse | APU_R | +| AGRPortfolioQuery | APQ | +| AGRPortfolioQueryResponse | APQ_R | +| DSOPortfolioUpdate | DPU | +| DSOPortfolioUpdateResponse | DPU_R | +| DSOPortfolioQuery | DPQ | +| DSOPortfolioQueryResponse | DPQ_R | +| FlexReservationUpdate | FRU | +| FlexReservationUpdateResponse | FRU_R | +| D-Prognosis | DP | +| D-PrognosisResponse | DP_R | +| FlexRequest |FR | +| FlexRequestResponse | FR_R | +| FlexOffer | FOF | +| FlexOfferResponse | FOF_R | +| FlexOfferRevocation | FOFR | +| FlexOfferRevocationResponse | FOFR_R | +| FlexOrder | FOR | +| FlexOrderResponse | FOR_R | +| Metering | M | +| MeteringResponse | M_R | +| FlexSettlement | FS | +| FlexSettlementResponse | FS_R | diff --git a/specifications/development/docs/use-case-descriptions/privacy-and-security-by-design.md b/specifications/development/docs/use-case-descriptions/privacy-and-security-by-design.md new file mode 100644 index 00000000..aac6b580 --- /dev/null +++ b/specifications/development/docs/use-case-descriptions/privacy-and-security-by-design.md @@ -0,0 +1,32 @@ + + +# Privacy and security by design + +USEF – like most complex information systems – deals with sensitive data and therefore requires security and privacy preservation measures. +Privacy & security are system-wide issues; protection of individual subsystems/components is not enough; the system is as strong as the weakest link. +USEF therefore follows the principle of privacy & security by design. + +USEF provides a separate privacy and security guideline [^B5] that lists approximately 50 design principles which, combined, present a complete view of the privacy and security aspects associated with smart energy systems. +It takes into account the current legal and social views on privacy & security and links these to the future directions in which they will likely evolve. + +[^B5]: USEF Foundation, "USEF: The Privacy and Security Guideline," USEF Foundation, Arnhem, 2015. Available: [https://www.usef.energy/app/uploads/2016/12/USEF_PrivacySecurityGuideline_3nov15.pdf](https://www.usef.energy/app/uploads/2016/12/USEF_PrivacySecurityGuideline_3nov15.pdf) + +The guideline forms the basis for the logical security architecture that is reflected in USEF’s process flows and use cases. +Some remarks about security and responsibility: + +- Personal and personally identifiable data represent commercially sensitive information. These include: + - connection identifiers + - existence of congestion points + - details on AGRs associated to a connection + - portfolio data + - forecast data, content of D-prognoses and the fact whether or not a given AGR submitted a D-prognosis in a timely fashion + - the existence, content and timing of a flexibility request and other flexibility trading messages + - settlement items, including the acknowledgement or disputation of their correctness +- Personal and personally identifiable data (such as forecasts or smart meter readings) should not be retained longer than strictly required. The retention period should be specified and be communicated to the data subject. +- The exact identity of the AGR for each connection should not be disclosed to the DSO. Instead, only aggregate connection counts should be provided (which represent commercially sensitive information). +- It is the responsibility of the CRO to have policies regarding access, data retention, data security and conflict resolution compliant with the USEF privacy & security guidelines. +- The CRO should only disclose the existence of the congestion point on a need-to-know basis, i.e. only to those AGRs which provide an associated connection identifier in their queries. diff --git a/specifications/development/docs/use-case-descriptions/reading-guidelines.md b/specifications/development/docs/use-case-descriptions/reading-guidelines.md new file mode 100644 index 00000000..cce12bab --- /dev/null +++ b/specifications/development/docs/use-case-descriptions/reading-guidelines.md @@ -0,0 +1,19 @@ + + +# Reading guidelines + +This chapter contains separate sections per USEF phase: Plan, Validate, Operate, and Settle. +In each section the use cases are specified in a standard table format: + +_Standard table format for USEF use cases._ + +| | | +|------------------------|------------------------------------------------------------------------------------------------------------------------------| +| **Goal in context** | High-level description of the activity. | +| **Preconditions** | The state of the system that must be present prior to a use case being performed. | +| **Successful outcome** | The state the system will be in immediately after a use case has finished without failure. | +| **Failure outcome** | The state the system will be in immediately after a use case has finished after failure, plus identification of the failure. | diff --git a/specifications/development/docs/use-case-descriptions/scope.md b/specifications/development/docs/use-case-descriptions/scope.md new file mode 100644 index 00000000..02d9a534 --- /dev/null +++ b/specifications/development/docs/use-case-descriptions/scope.md @@ -0,0 +1,30 @@ + + +# Scope + +This chapter provides details of the functions that contain interactions relevant to the DSO and AGR, in order to be active in the USEF MCM. +To be USEF compliant, these functions must be implemented according to the use case descriptions in this chapter. + +The use cases have been derived from the MCM sequence diagrams detailed in Chapter [General description](../general-description/index.md). +Use cases are separate activities that require interaction between DSO and AGR, each containing multiple messages in both directions. +DSO and AGR internal processes are not addressed in this chapter. + +The messages types that occur in these use cases are mentioned and further described in Section [Message catalog](../message-descriptions/message-catalog/index.md). + +## Introduction + +The core of the USEF specification is the MCM and the processes governing it. +These define how the different stakeholders active in the MCM should behave and interact. +All use cases related to these functions are described to the extent relevant for the USEF specifications. +All aspects not specified by USEF are explicitly mentioned. +An example of this is that USEF does not specify how an AGR optimizes its portfolio or determines how much flexibility is available, where or when. +The result of this portfolio optimization is, however, a prerequisite for participating in the flexibility bidding process. + +For the flexibility market to function, it is essential to have a functioning common reference populated with all AGR-represented connections. + +Given the open nature of the USEF specifications, any implementation can choose to adopt all or only part of the specifications. +In any situation, all participants within a single USEF market will have to adopt a common specification of the market processes and information exchange. diff --git a/specifications/development/docs/use-case-descriptions/use-cases/contract-phase.md b/specifications/development/docs/use-case-descriptions/use-cases/contract-phase.md new file mode 100644 index 00000000..2c07b586 --- /dev/null +++ b/specifications/development/docs/use-case-descriptions/use-cases/contract-phase.md @@ -0,0 +1,141 @@ + + +# Contract phase + +In [Contract phase](../../general-description/contract-phase.md) the informative description of the contract phase processes has been given. +In this chapter use cases will be described as derived from the contract phase. + +The USEF MCM contract phase specifies the following use cases: + +_Use cases for the Contract phase._ + +| Name | Direction | Message types | +|-------------------------------------------------------------------------------|-----------|-------------------------------------------------| +| [Publish Congestion Points (Long-term)](#publish-congestion-points-long-term) | DSO → CRO | DSOPortfolioUpdate / DSOPortfolioUpdateResponse | +| [Publish Connections](#publish-connections) | AGR → CRO | AGRPortfolioUpdate / AGRPortfolioUpdateResponse | + +## Publish Congestion Points (Long-term) + +Once a flexibility market is functional for an area, the DSO has to update and publish a register of possible congestion points, including the connection identifiers of connected prosumers. +This register is maintained by the Common Reference Operator. +If operating in open mode, the CRO will accept updates from any USEF-compliant participants implementing the DSO role. +In closed mode, participants will need to be pre-configured in order for updates to be accepted. + +Once populated, the common reference will allow AGRs to determine whether there are prosumers in their portfolio that can offer flexibility, via their connections, to one or more congestion points. + +
+ ![Exchange of congestion points including connections by DSO](../../diagrams/use-case-3-1-exchange-of-congestions-points.puml){ .no-lightbox } +
Exchange of congestion points including connections by DSO
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Publish Congestion Points / DSO Portfolio
Goal in contextIn order to predict congestion and create a flex market: publish Congestion Points – including their associated Connections – to the Common Reference, so they become available to the AGRs.
PreconditionsCommon Reference is available to DSO and AGRs
Successful outcomeThe Common Reference is updated with the latest Congestion points and associated Connections (i.e. all connected Prosumers)
Failure outcomeRejectionReasonCause of rejection
<See Message validation>DSOPortfolioUpdate failed to pass validation by the CRO
UnauthorizedCRO is operating in closed mode and the DSO is not pre-registered as an authorized participant
Subordinate sequence numberThe message sequence is lower than that of a previously received DSOPortfolioUpdate
[User defined]Any other reasonable cause to reject the message
+ +### Related information + +It is the responsibility of the CRO to have policies regarding access, data retention, data security and conflict resolution compliant with the USEF privacy & security guidelines. +If the CRO detects strange behavior in the periods (e.g.an EndPeriod in the far past, an EndPeriod earlier than the StartPeriod or an EndPeriod of a congestion point earlier than the EndPeriod of a connection that it contains), it is up to the CRO to decide whether to reject the message, adjust the period or reply with a warning. + +A DSO can update its portfolio by retransmitting the DSOPortfolioUpdate. +It is essential to use a sequence number that is incremented each time a new revision is sent so the order of transmission can be traced. +To remove a congestion point, the DSO can transmit a new DSOPortfolioUpdate where the EndPeriod is the current time. +The congestion point is then immediately expired. +It is not necessary to add connections to this message since they will also expire. + +## Publish Connections + +Once a flexibility market is functional for an area, the AGR has to publish a list of the connection identifiers of the prosumers it has contracted. +This list is stored and, subject to access controls, made available to other market participants by the CRO. + +
+ ![Exchange of connections by AGR](../../diagrams/use-case-3-2-exchange-of-connections-by-agr.puml){ .no-lightbox } +
Exchange of connections by AGR
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Publish Congestion Points / DSO Portfolio
Goal in contextPublish all contracted Prosumer Connections in the Common Reference, in order to later discover Congestion Points and associated DSOs and to register the AGR’s presence at Connections to the associated DSOs.
PreconditionsCommon Reference is available to DSO and AGRs
Successful outcomeThe Common Reference is updated with the all Prosumers (listed by their Connection identifiers) represented by the AGR.
Failure outcomeRejectionReasonCause of rejection
<See Message validation>AGRPortfolioUpdate failed to pass validation by the CRO
UnauthorizedCRO is operating in closed mode and the AGR is not pre-registered as an authorized participant
Subordinate sequence numberThe message sequence is lower than that of a previously received DSOPortfolioUpdate
[User defined]Any other reasonable cause to reject the message
+ +### Related information + +It is possible to transmit connection points to the CRO that have not yet been declared by the DSO. + +An AGR can update its portfolio by retransmitting the AGRPortfolioUpdate. +It is essential to use a sequence number that is incremented each time a new revision is sent, so the order of transmission can be traced. diff --git a/specifications/development/docs/use-case-descriptions/use-cases/operate-phase.md b/specifications/development/docs/use-case-descriptions/use-cases/operate-phase.md new file mode 100644 index 00000000..059a91e2 --- /dev/null +++ b/specifications/development/docs/use-case-descriptions/use-cases/operate-phase.md @@ -0,0 +1,182 @@ + + +# Operate phase + +In [Operate phase](../../general-description/operate-phase.md) the informative description of the operate phase processes are provided. +In this chapter, the use cases will be described as derived from the operate phase. + +The USEF MCM operate phase specifies the following use cases: + +_Use cases for the operate phase._ + +| Name | Direction | Message types | +|---------------------------------------------------------------|-----------|---------------------------------------------------| +| [Exchange updated D-Prognoses](#exchange-updated-d-prognoses) | AGR → DSO | Prognosis / PrognosisResponse | +| [Revocation Flexibility Offer](#revocation-flexibility-offer) | AGR → DSO | FlexOfferRevocation / FlexOfferRevocationResponse | +| [Exchange Flexibility Orders](#exchange-flexibility-orders) | AGR ← DSO | FlexOrder / FlexOrderResponse | + +The use cases are explained in the following sections. + +## Exchange updated D-Prognoses + +The process diagram is similar to the figure in [Exchange D-Prognoses per Congestion Point](validate-phase.md#exchange-d-prognoses-per-congestion-point). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
D-prognosis
Goal in contextChanges in D-prognoses to be realized are transmitted.
PreconditionsAGR has created initial D-prognoses in the Plan/Validate phases, and has subsequently detected deviations in Operate that resulted in a portfolio state that requires those prognoses to be re-created.
Successful outcomePrognosis sent to DSO that reflects all relevant changes
Failure outcomeRejectionReasonCause of rejection
<See Message validation>D-prognosis failed to pass validation by the DSO
Lacking ISPsThe prognosis does not include all ISPs in the Period it applies to
Power value rejectionOne or more Power values in the prognosis are not plausible
Subordinate sequence numberThe message sequence is lower than that of a previously received D-prognosis
[User defined]Any other reasonable cause to reject the message
+ +### Related information + +The process is similar to that described in [Exchange D-Prognoses per Congestion Point](validate-phase.md#exchange-d-prognoses-per-congestion-point). +Deviations can be caused by new flexibility orders from the DSO and by unforeseen change of behavior by assets. + +The basic process for re-creating D-prognoses is the same as that used to create them in the first place, in the plan/validate phases. +When re-creating prognoses in the operate phase, values for ISPs that are already in the past should remain unchanged, as these will be ignored by DSOs anyway. + +## Revocation Flexibility Offer + +The process diagram is similar to the figure in [Revocation of FlexOffer](validate-phase.md#revocation-flexibility-offer). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Revoke FlexOffer
Goal in contextInform the DSO that a previously sent flexibility offer is no longer valid, despite the validity period of the offer not having expired yet.
PreconditionsA flexibility offer has been sent to and acknowledged by the DSO
Successful outcomeFlexibility offer revocation notification submitted to the DSO
Failure outcomeRejectionReasonCause of rejection
<See Message validation>FlexOfferRevocation failed to pass validation by the DSO
Flexibility procuredThe FlexOffer cannot be revoked because its flexibility has already been ordered
[User defined]Any other reasonable cause to reject the message
+ +### Related information + +The process is similar to that described in [Revocation Flexibility Offer](validate-phase.md#revocation-flexibility-offer). + +Flexibility offers may be revoked in the operate phase provided that none of the ISPs in the period the offer applies to are +already in, or past, the operate phase. + +## Exchange Flexibility Orders + +This process is triggered when flexibility is required to resolve congestion detected during the operate phase. +This might, for example, be the case when the prognoses change after the validate phase and there are still FlexOffers available. + +The process diagram is similar to the figure in [Exchange Flexibility Orders](validate-phase.md#exchange-flexibility-orders). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Revoke FlexOrder
Goal in contextAccept (some) flexibility offers to solve congestion during Operate phase.
PreconditionsCongestion detected while monitoring the grid, corresponding FlexOffer has been received and accepted by DSO and is still valid.
Successful outcomeFlexibility procured
Failure outcomeRejectionReasonCause of rejection
<See Message validation>FlexOrder failed to pass validation by the AGR
ISP mismatchISPs from the FlexOrder do not match the ISPs given in the FlexOffer
Power mismatchOrdered flexibility does not match the offered flexibility
Price mismatchPrice in the order does not match the price given in the offer
[User defined]Any other reasonable cause to reject the message
+ +### Related information + +The process is similar to that described in [Exchange Flexibility Orders](validate-phase.md#exchange-flexibility-orders). +Note that where a FlexOrder is rejected, manual processing is unlikely to result in timely resolution at this stage. +Note that although the updated D-prognosis is unlikely to be of immediate use to the DSO, it’s definitely required for settlement. diff --git a/specifications/development/docs/use-case-descriptions/use-cases/plan-phase.md b/specifications/development/docs/use-case-descriptions/use-cases/plan-phase.md new file mode 100644 index 00000000..76065155 --- /dev/null +++ b/specifications/development/docs/use-case-descriptions/use-cases/plan-phase.md @@ -0,0 +1,184 @@ + + +# Plan phase + +In [Plan phase](../../general-description/plan-phase.md) the informative description of the plan phase processes are provided. +In this chapter, use cases will be described as derived from the plan phase. + +The USEF MCM plan phase specifies the following use cases: + +_Use cases for the Plan phase._ + +| Name | Direction | Message types | +|-------------------------------------------------------------------------------------|-----------|-------------------------------------------------------| +| [Retrieve Congestion Points](#retrieve-congestion-points) | AGR → CRO | AGRPortfolioQuery / AGRPortfolioQueryResponse | +| [Retrieve Active Aggregators](#retrieve-active-aggregators) | DSO → CRO | DSOPortfolioQuery / DSOPortfolioQueryResponse | +| [Exchange Flexibility Reservation Update](#exchange-flexibility-reservation-update) | AGR ← DSO | FlexReservationUpdate / FlexReservationUpdateResponse | + +The use cases are explained in the following sections. + +If operating in open mode, the CRO will accept updates from any USEF-compliant participants implementing the AGR role. +In closed mode, participants will need to be pre-configured in order for updates to be accepted. + +## Retrieve Congestion Points + +The common reference allows an AGR to determine whether there are any congestion points where prosumers in its portfolio +can offer flexibility. + +
+ ![Retrieval of Congestion Points corresponding to AGR's connections](../../diagrams/use-case-3-3-retrieval-of-congestion-points.puml){ .no-lightbox } +
Retrieval of Congestion Points corresponding to AGR's connections
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Publish Congestion Points / DSO Portfolio
Goal in contextRetrieve a list of all registered Connections represented by this AGR, grouped by Congestion Point, in order to enable flex trading with the responsible DSO.
PreconditionsThe AGR has registered the Connection identifiers for which it represents Prosumers in the Common Reference.
Successful outcomeThe AGR receives a list of Connections, grouped by Connection Point and responsible DSO, and a list of Connections that have not been allocated to a DSO.
Failure outcomeRejectionReasonCause of rejection
<See Message validation>AGRPortfolioQuery failed to pass validation by the CRO
UnauthorizedCRO is operating in closed mode and the AGR is not pre-registered as an authorized participant
No connections availableThe AGR has no registered connections at the Common Reference
[User defined]Any other reasonable cause to reject the message
+ +### Related information + +AGRs will only obtain DSO identities, congestion point identifiers and connection identifiers for those connections they have registered in the common reference themselves. + +Registered connections that have not (yet) been allocated by a DSO are returned in a separate list, to inform the AGR that there is no DSO available to trade with at those connections. + +## Retrieve Active Aggregators + +If operating in open mode, the CRO will accept queries from any USEF-compliant participants implementing the AGR role. +In closed mode, participants will need to be pre-configured in order for updates to be accepted. + +
+ ![Retrieval of registered Connections, grouped by Congestion Point, including corresponding AGR identity](../../diagrams/use-case-3-4-retrieval-of-registered-connections.puml){ .no-lightbox } +
Retrieval of registered Connections, grouped by Congestion Point, including corresponding AGR identity
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Publish Congestion Points / DSO Portfolio
Goal in contextRetrieve a list of all DSO-registered Congestion Points with, for each such point, a list of AGRs representing Prosumers there, including the number of Connections each AGR represents.

The DSO then knows from which AGRs D-prognoses can be expected, and which percentage of the total Connections on each Congestion Point is affected by those prognoses.
PreconditionsThe DSO has determined its Congestion Points and published this information, including the associated Connection identifiers in the Common Reference.
The AGR has registered the Connection identifiers for which it represents Prosumers in the Common Reference (see UC1027)
Successful outcomeAGRs which represent Prosumers at any of the Congestion Points registered by the DSO are available to the DSO
Failure outcomeRejectionReasonCause of rejection
<See Message validation>DSOPortfolioQuery failed to pass validation by the CRO
UnauthorizedCRO is operating in closed mode and the AGR is not pre-registered as an authorized participant
No connections availableThe DSO has no registered connections at the Common Reference
[User defined]Any other reasonable cause to reject the message
+ +### Related information + +DSOs may only obtain AGR identities and combined connection counts for those congestion points they have registered in the common reference themselves. + +## Exchange Flexibility Reservation Update + +Where bilateral contracts are used, the FlexReservationUpdate message can be used at this stage to set or release reserved flexibility. + +
+ ![Exchange of FlexReservationUpdate](../../diagrams/use-case-3-5-exchange-of-flexreservationupdate.puml){ .no-lightbox } +
Exchange of FlexReservationUpdate
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Publish Congestion Points / DSO Portfolio
Goal in contextFor all reserved power in a bilateral contract, the DSO signals which part of the contracted volume is still reserved and which part is not needed and may be used for other purposes.
PreconditionsThe DSO and AGR have agreed on a bilateral contract (out of scope for UFTP) which the FlexReservationUpdate refers to.
Successful outcomeThe AGR has received the update and can potentially reoptimize its portfolio based on the changes. The DSO registers the update for settlement purposes.
Failure outcomeRejectionReasonCause of rejection
<See Message validation>FlexReservationUpdate failed to pass validation by the AGR
Deadline expiredThe deadline for the DSO to release reserved flexibility has expired
Power value rejectionOne or more Power values in the FlexReservationUpdate are not conform agreement
[User defined]Any other reasonable cause to reject the message
diff --git a/specifications/development/docs/use-case-descriptions/use-cases/settle-phase.md b/specifications/development/docs/use-case-descriptions/use-cases/settle-phase.md new file mode 100644 index 00000000..99b82af2 --- /dev/null +++ b/specifications/development/docs/use-case-descriptions/use-cases/settle-phase.md @@ -0,0 +1,77 @@ + + +# Settle phase + +The informative description of the settle phase processes are provided in [Settle phase](../../general-description/settle-phase.md). +In this chapter, the use cases will be described, as derived from the settle phase. + +The USEF MCM settle phase specifies the following use case: + +_Use cases for the settle phase._ + +| Name | Direction | Message types | +|-------------------------------------------------------|-----------|----------------------------------------| +| [Process Settlement Items](#process-settlement-items) | AGR ← DSO | FlexSettlement/ FlexSettlementResponse | + +## Process Settlement Items + +
+ ![Transmission of settlement including acceptance process per settlement item](../../diagrams/use-case-3-11-transmission-of-settlement.puml){ .no-lightbox } +
Transmission of settlement including acceptance process per settlement item
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Revoke FlexOrder
Goal in contextDSO sends consolidated settlement volumes and prices to the AGR for a specific period. AGR verifies the settlement calculations performed by DSO: acknowledge settlement items that are plausible according to the AGR or start a dispute process if they show disputable results. AGR returns the list of verified settlement items.
PreconditionsAll settlement items within the period are available and complete
Successful outcomePeriodic settlement invoice sent by DSO, validated by AGR and a potential dispute process is started.
Failure outcomeRejectionReasonCause of rejection
<See Message validation>FlexSettlement failed to pass validation by the AGR
Missing Settlement ItemsNot all flexibility that have been procured within the given period is included as a settlement item.
PeriodStart rejectedThe settlement period starts too late (for example in case there are unsettled items from an earlier period) or is not plausible (for example in case it starts in the future).
PeriodEnd rejectedThe settlement period ends too early (for example in case there are unsettled items from a later period that have to be treated too) or is not plausible (for example in case it is earlier than the PeriodStart or in the future).
[User defined]Any other reasonable cause to reject the message
+ +### Related information + +If settlement items are missing, the message should be rejected (as mentioned in failure outcome). +This is to encourage sending of all required information necessary to settle trades as soon as possible, thereby avoiding a series of unsettled trades for a given period. + +Note that the rejection of a FlexSettlement message is not a means of raising a dispute for settlement items. +The dispute process is out-of-scope for USEF. diff --git a/specifications/development/docs/use-case-descriptions/use-cases/validate-phase.md b/specifications/development/docs/use-case-descriptions/use-cases/validate-phase.md new file mode 100644 index 00000000..8b34ad93 --- /dev/null +++ b/specifications/development/docs/use-case-descriptions/use-cases/validate-phase.md @@ -0,0 +1,363 @@ + + +# Validate phase + +In [Validate phase](../../general-description/validate-phase.md), informative description of the validate phase processes has been given. In this chapter the use cases will be described as derived from the validate phase. + +The USEF MCM validate phase specifies the following use cases: + +_Use cases for the Validate phase._ + +| Name | Direction | Message types | +|-----------------------------------------------------------------------------------------|-----------|---------------------------------------------------| +| [Exchange D-Prognoses per Congestion Point](#exchange-d-prognoses-per-congestion-point) | AGR → DSO | Prognosis / PrognosisResponse | +| [Exchange Flexibility Requests](#exchange-flexibility-requests) | AGR ← DSO | FlexRequest / FlexRequestResponse | +| [Exchange Flexibility Offers](#exchange-flexibility-offers) | AGR → DSO | FlexOffer / FlexOfferResponse | +| [Revocation Flexibility Offer](#revocation-flexibility-offer) | AGR → DSO | FlexOfferRevocation / FlexOfferRevocationResponse | +| [Exchange Flexibility Orders](#exchange-flexibility-orders) | AGR ← DSO | FlexOrder / FlexOrderResponse | + +The use cases are explained in the following sections. + +## Exchange D-Prognoses per Congestion Point + +
+ ![Exchange of D-prognoses](../../diagrams/use-case-3-6-exchange-of-d-prognoses.puml){ .no-lightbox } +
Exchange of D-prognoses
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
D-prognosis
Goal in contextD-prognoses are (re)created by the AGR per congestion point, based on its portfolio. These D-prognoses will be submitted to the DSO. D-prognoses should be submitted at least once before the gate closure time. D-prognoses can be updated by transmitting a new one.
PreconditionsCongestion point(s) defined and retrieved from the CRO, AGR per congestion point retrieved from CRO by DSO, AGR-DSO contracts in place.
Successful outcomeD-prognosis message created and accepted by the DSO for each congestion point on which the AGR has active Connections
Failure outcomeRejectionReasonCause of rejection
<See Message validation>D-prognosis failed to pass validation by the DSO
Lacking ISPsThe prognosis does not include all ISPs in the Period it applies to
Power value rejectionOne or more Power values in the prognosis are not plausible
Subordinate sequence numberThe message sequence is lower than that of a previously received D-prognosis
[User defined]Any other reasonable cause to reject the message
+ +### Related information + +Congestion points (with associated DSOs) at which the AGR has contracted prosumers, and active AGRs, are available via the common reference and should have been retrieved prior to executing this use case. + +It is essential to use a sequence number that is incremented each time a new revision is sent so the order of transmission can be traced. + +## Exchange Flexibility Requests + +
+ ![Exchange of FlexRequests](../../diagrams/use-case-3-7-exchange-of-flexrequests.puml){ .no-lightbox } +
Exchange of FlexRequests
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlexRequest
Goal in contextIf grid congestion is expected, requests for flexibility are created by the DSO and sent to AGRs potentially capable of helping to reduce that congestion. These requests serve as the basis for subsequent flexibility offers.
PreconditionsAGR-DSO market contract in place.
One or more Congestion Points registered in the Common Reference, with at least one AGR with contracted Connections on that point.
DSO grid safety analysis performed.
Successful outcomeFlexibility requests submitted to AGR(s)
Failure outcomeRejectionReasonCause of rejection
<See Message validation>FlexRequest failed to pass validation by the AGR
Lacking Requested DispositionThe FlexRequest has no ISP with a “requested” disposition.
Requested Power discrepancyOne or more ISPs with a "requested" disposition has no direction: MinPower < 0 and MaxPower > 0.
Power discrepancyOne or more ISPs has a higher MinPower than MaxPower value.
[User defined]Any other reasonable cause to reject the message
+ +### Related information + +Each flexibility request should include the ISPs for which congestion is expected, including a direction (MinPower ≥ 0 or MaxPower ≤ 0), and it is advisable to send multiple ISPs for which capacity is still available, to allow AGRs to time-shift load. +For each period during which congestion is expected, the DSO may create any number of flexibility requests (including no requests at all). +If multiple requests are created, their content must not be identical. +Which variations (more/less requested power per ISP, time-shift of load) are created is a DSO-internal business decision. + +## Exchange Flexibility Offers + +
+ ![Exchange of FlexOffers](../../diagrams/use-case-3-8-exchange-of-flexoffers.puml){ .no-lightbox } +
Exchange of FlexOffers
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlexOffer
Goal in contextThe AGR creates flexibility offers based on previous DSO flexibility requests and sends these to the originating DSOs. It is also possible to send FlexOffers that do not originate from a FlexRequest, which are called unsolicited FlexOffers. Each offer indicates to which extent the AGR can provide flexibility, what the effect on its baseline will be and what the price for the flexibility would be.
PreconditionsAGR-DSO market contract in place.
AGR has at least one contracted Connection on the Congestion point. Flexibility offers can be based on previous flexibility requests that have been accepted and stored, or be initiated without a preliminary flex request (called an unsolicited flex offer).
Successful outcomeFlexibility offers sent to the DSO
Failure outcomeRejectionReasonCause of rejection
<See Message validation>FlexOffer failed to pass validation by the DSO
No baselineThe AGR has no valid baseline, possibly lacking a valid D-prognosis
Power value rejectionOne or more Power values in the FlexOffer are not plausible
Request mismatchNone of the ISPs with a "requested" disposition in the referred FlexRequest, is mentioned in the FlexOffer
No MutEx offer supportThe FlexOffer contains mutual exclusive offers (OfferOptions), which is not supported by the DSO
[User defined]Any other reasonable cause to reject the message
+ +### Related information + +- USEF does not specify how the AGR determines the optimal flexibility offer, offer price or optimal timing to send the offer to the DSO. +- AGRs may choose to send multiple FlexOffer messages: this includes sending a FlexOffer that better meets the DSO request at a much later time when circumstances have changed. +Unsolicited FlexOffers are also allowed, in which case the FlexRequestOrigin and FlexRequestSequence fields are empty. +- Sending a FlexOffer for partial activation is always allowed, although it is ignored by the DSO if it does not support partial activation (in which case the MinActivationFactor is always 1). + +Note that acceptance of the FlexOffer message does not imply ordering of the flexibility. + +## Revocation Flexibility Offer + +
+ ![Revocation of FlexOffer](../../diagrams/use-case-3-9-revocation-of-flexoffer.puml){ .no-lightbox } +
Revocation of FlexOffer
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Revoke FlexOffer
Goal in contextWhen a previously sent flexibility offer is no longer valid, despite the validity period of the offer not having expired yet, the AGR informs the DSO that the offer is revoked. After revocation, the DSO cannot order the flexibility from this offer anymore.
PreconditionsThe concerning flexibility offer has been sent to and acknowledged by the DSO, and has not (yet) been procured using a FlexOrder
Successful outcomeFlexibility offer revocation notification submitted to the DSO
Failure outcomeRejectionReasonCause of rejection
<See Message validation>FlexOfferRevocation failed to pass validation by the DSO
Flexibility procuredThe FlexOffer cannot be revoked because its flexibility has already been ordered
[User defined]Any other reasonable cause to reject the message
+ +### Related information + +Only flexibility offers communicated using a FlexOffer message which has already been acknowledged by the DSO can be revoked. +If the acknowledgement is still pending, the AGR should delay sending its FlexOfferRevocation message until the acknowledgement has been received. +When the DSO receives a revocation of a flexibility offer it wants to order, this is not a valid base to reject the revocation. +After revocation, the offer can no longer be ordered. + +FlexOffers may be revoked at any time in the plan and validate phases (and also in operate phase as described in [Revocation Flexibility Offer](operate-phase.md#revocation-flexibility-offer)), unless there is already a FlexOrder based on the offer. +Notice that FlexOrders and FlexOfferRevocations can cross each other. +Where this is the case, priority should be given to the FlexOfferRevocation. + +## Exchange Flexibility Orders + +### Accepting a FlexOffer + +
+ ![Exchange of FlexOrder](../../diagrams/use-case-3-10-exchange-of-flexorder.puml){ .no-lightbox } +
Exchange of FlexOrder
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlexOrder
Goal in contextProcess for the DSO to accept (some) flexibility offers to solve Congestion based on the Prognosis.
PreconditionsCorresponding FlexOffer has been received and accepted by DSO and is still valid.
Successful outcomeFlexibility procured
Failure outcomeRejectionReasonCause of rejection
<See Message validation>FlexOrder failed to pass validation by the AGR
ISP mismatchISPs from the FlexOrder do not match the ISPs given in the FlexOffer
Power mismatchOrdered flexibility does not match the offered flexibility
Price mismatchPrice in the order does not match the price given in the offer
[User defined]Any other reasonable cause to reject the message
+ +### FlexOrder without offer + +
+ ![Exchange of FlexOrder without FlexOffer](../../diagrams/use-case-3-10-exchange-of-flexorder-direct.puml){ .no-lightbox } +
Exchange of FlexOrder without FlexOffer
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlexOrder
Goal in contextProcess for the DSO to procure flexibility directly, without a FlexOffer, based on existing agreement, to solve Congestion based on the Prognosis.
PreconditionsAGR-DSO market contract in place.
One or more Congestion Points registered in the Common Reference, with at least one AGR with contracted Connections on that point.
DSO grid safety analysis performed.
Successful outcomeFlexibility procured
Failure outcomeRejectionReasonCause of rejection
<See Message validation>FlexOrder failed to pass validation by the AGR
Requested Power discrepancyOne or more ISPs with a "requested" disposition has no direction: MinPower < 0 and MaxPower > 0.
Power discrepancyOne or more ISPs has a higher MinPower than MaxPower value.
[User defined]Any other reasonable cause to reject the message
+ +### Related information + +The DSO needs to make its own decisions about which FlexOffers to accept. +FlexOffers can only be ordered once and have to be ordered as specified in the corresponding offer for the specified price. +Only in situations where partial activation is supported and offered in the FlexOffer can the ISP power and price be altered to conform to the specifications from Section [Flexibility trading between the AGR and DSO](../../general-description/validate-phase.md#flexibility-trading-between-the-agr-and-dso). +After a successful FlexOrder transmission, the AGR is responsible for providing the ordered flexibility via an updated D-prognosis which reflects the traded flexibility. diff --git a/specifications/development/docs/versions.md b/specifications/development/docs/versions.md new file mode 100644 index 00000000..299e2c9a --- /dev/null +++ b/specifications/development/docs/versions.md @@ -0,0 +1,19 @@ + + +# Versioned specification files + +The XSD links below point to immutable version snapshots in the repository. The v3 PDF and Word files are the original artifacts from their respective release tags. + +| Version | Markdown and images | XSD files | PDF | Word | +| --- | --- | --- | --- | --- | +| 1.0.1 | Not archived | [Browse XSDs](https://github.com/shapeshifter/shapeshifter-specification/tree/main/specifications/1.0.1/xsd) | Not archived | Not archived | +| 2.0.0 | Not archived | [Browse XSDs](https://github.com/shapeshifter/shapeshifter-specification/tree/main/specifications/2.0.0/xsd) | Not archived | Not archived | +| 3.0.0 | [Browse docs](https://github.com/shapeshifter/shapeshifter-specification/tree/main/specifications/3.0.0/docs) | [Browse XSDs](https://github.com/shapeshifter/shapeshifter-specification/tree/main/specifications/3.0.0/xsd) | [Download PDF](https://github.com/shapeshifter/shapeshifter-specification/blob/main/specifications/3.0.0/USEF%20Flex%20Trading%20Protocol%20Specifications%203.0.0.pdf?raw=1) | [Download Word](https://github.com/shapeshifter/shapeshifter-specification/blob/main/specifications/3.0.0/USEF%20Flex%20Trading%20Protocol%20Specifications%203.0.0.docx?raw=1) | +| 3.1.0 | [Browse docs](https://github.com/shapeshifter/shapeshifter-specification/tree/main/specifications/3.1.0/docs) | [Browse XSDs](https://github.com/shapeshifter/shapeshifter-specification/tree/main/specifications/3.1.0/xsd) | [Download PDF](https://github.com/shapeshifter/shapeshifter-specification/blob/main/specifications/3.1.0/USEF%20Flex%20Trading%20Protocol%20Specifications%203.1.0.pdf?raw=1) | [Download Word](https://github.com/shapeshifter/shapeshifter-specification/blob/main/specifications/3.1.0/USEF%20Flex%20Trading%20Protocol%20Specifications.docx?raw=1) | +| Development | [Browse docs](https://github.com/shapeshifter/shapeshifter-specification/tree/main/specifications/development/docs) | [Browse XSDs](https://github.com/shapeshifter/shapeshifter-specification/tree/main/specifications/development/xsd) | Not published | Not published | + +The header version selector links to the published documentation versions. The current draft is published at `/development/` and is not a numbered release. \ No newline at end of file diff --git a/xsd/UFTP-agr-cro.xsd b/specifications/development/xsd/UFTP-agr-cro.xsd similarity index 100% rename from xsd/UFTP-agr-cro.xsd rename to specifications/development/xsd/UFTP-agr-cro.xsd diff --git a/xsd/UFTP-agr-dso.xsd b/specifications/development/xsd/UFTP-agr-dso.xsd similarity index 100% rename from xsd/UFTP-agr-dso.xsd rename to specifications/development/xsd/UFTP-agr-dso.xsd diff --git a/xsd/UFTP-agr.xsd b/specifications/development/xsd/UFTP-agr.xsd similarity index 100% rename from xsd/UFTP-agr.xsd rename to specifications/development/xsd/UFTP-agr.xsd diff --git a/xsd/UFTP-common.xsd b/specifications/development/xsd/UFTP-common.xsd similarity index 100% rename from xsd/UFTP-common.xsd rename to specifications/development/xsd/UFTP-common.xsd diff --git a/xsd/UFTP-cro-dso.xsd b/specifications/development/xsd/UFTP-cro-dso.xsd similarity index 100% rename from xsd/UFTP-cro-dso.xsd rename to specifications/development/xsd/UFTP-cro-dso.xsd diff --git a/xsd/UFTP-cro.xsd b/specifications/development/xsd/UFTP-cro.xsd similarity index 100% rename from xsd/UFTP-cro.xsd rename to specifications/development/xsd/UFTP-cro.xsd diff --git a/xsd/UFTP-dso.xsd b/specifications/development/xsd/UFTP-dso.xsd similarity index 100% rename from xsd/UFTP-dso.xsd rename to specifications/development/xsd/UFTP-dso.xsd diff --git a/xsd/UFTP-metering.xsd b/specifications/development/xsd/UFTP-metering.xsd similarity index 100% rename from xsd/UFTP-metering.xsd rename to specifications/development/xsd/UFTP-metering.xsd