diff --git a/.devcontainer/post.sh b/.devcontainer/post.sh index e86e46ec..0a147b29 100755 --- a/.devcontainer/post.sh +++ b/.devcontainer/post.sh @@ -33,8 +33,8 @@ if [[ ("${1,,}" == "bundle") || ("${1,,}" == "start") ]]; then if [[ -n "$BUNDLE_PID" && -n "$(ps -p $BUNDLE_PID)" ]]; then kill $BUNDLE_PID fi - redocly bundle $DOCS_PATH/_spec/openapi-split.yaml -o $DOCS_PATH/openapi.yaml && \ - npx @redocly/cli lint ./docs/openapi.yaml & + redocly bundle $DOCS_PATH/_spec/openapi-split.yaml -o $DOCS_PATH/openapi-1.0.yaml && \ + npx @redocly/cli lint ./docs/openapi-1.0.yaml & export BUNDLE_PID=$! fi diff --git a/.github/workflows/crunch42-security-audit.yaml b/.github/workflows/crunch42-security-audit.yaml index 238e0382..dd2faa9d 100644 --- a/.github/workflows/crunch42-security-audit.yaml +++ b/.github/workflows/crunch42-security-audit.yaml @@ -18,7 +18,7 @@ jobs: node-version: 20 - name: Bundle run: >- - npx --yes @redocly/cli bundle ./docs/_spec/openapi-split.yaml -o ./docs/openapi.yaml && + npx --yes @redocly/cli bundle ./docs/_spec/openapi-split.yaml -o ./docs/openapi-1.0.yaml && rm ./docs/_spec/openapi-split.yaml - name: Audit API definition for security issues diff --git a/.github/workflows/documentation.yaml b/.github/workflows/documentation.yaml index 0026982f..485c5acd 100644 --- a/.github/workflows/documentation.yaml +++ b/.github/workflows/documentation.yaml @@ -4,7 +4,7 @@ on: workflow_dispatch: push: branches: - - 1.0.0* + - 1.0* permissions: contents: read @@ -28,7 +28,7 @@ jobs: with: node-version: 20 - name: Redocly bundle - run: "npx --yes @redocly/cli bundle ./docs/_spec/openapi-split.yaml -o ./docs/openapi.yaml" + run: "npx --yes @redocly/cli bundle ./docs/_spec/openapi-split.yaml -o ./docs/openapi-1.0.yaml" - name: Setup Ruby uses: ruby/setup-ruby@v1.98.0 diff --git a/.github/workflows/lint.yaml b/.github/workflows/lint.yaml index 5864208f..f843196f 100644 --- a/.github/workflows/lint.yaml +++ b/.github/workflows/lint.yaml @@ -4,7 +4,7 @@ on: workflow_dispatch: pull_request: branches: - - 1.0.0* + - 1.0* permissions: contents: read @@ -24,11 +24,11 @@ jobs: with: node-version: 20 - run: >- - npx --yes @redocly/cli bundle ./docs/_spec/openapi-split.yaml -o ./docs/openapi.yaml && - npx @redocly/cli lint ./docs/openapi.yaml + npx --yes @redocly/cli bundle ./docs/_spec/openapi-split.yaml -o ./docs/openapi-1.0.yaml && + npx @redocly/cli lint ./docs/openapi-1.0.yaml - name: Redocly API Stats id: api_stats - run: npx @redocly/cli stats ./docs/openapi.yaml > stats.txt 2>&1 + run: npx @redocly/cli stats ./docs/openapi-1.0.yaml > stats.txt 2>&1 - name: Comment PR with API Stats #if: ${{ github.event.pull_request }} if: ${{ false }} diff --git a/.github/workflows/owasp.yaml b/.github/workflows/owasp.yaml index 1e528d89..de387741 100644 --- a/.github/workflows/owasp.yaml +++ b/.github/workflows/owasp.yaml @@ -4,10 +4,10 @@ on: workflow_dispatch: push: branches: - - 1.0.0* + - 1.0* pull_request: branches: - - 1.0.0* + - 1.0* permissions: contents: read @@ -27,5 +27,5 @@ jobs: node-version: 20 - name: Lint run: >- - npx --yes @redocly/cli bundle ./docs/_spec/openapi-split.yaml -o ./docs/openapi.yaml && - npx --yes @stoplight/spectral-cli lint docs/openapi.yaml --ruleset .spectral.yaml --verbose + npx --yes @redocly/cli bundle ./docs/_spec/openapi-split.yaml -o ./docs/openapi-1.0.yaml && + npx --yes @stoplight/spectral-cli lint docs/openapi-1.0.yaml --ruleset .spectral.yaml --verbose diff --git a/.github/workflows/prebuild.yaml b/.github/workflows/prebuild.yaml index 609cd409..ab3b4a38 100644 --- a/.github/workflows/prebuild.yaml +++ b/.github/workflows/prebuild.yaml @@ -4,7 +4,7 @@ on: workflow_dispatch: push: branches: - - 1.0.0* + - 1.0* jobs: build-and-push: runs-on: ubuntu-latest diff --git a/.github/workflows/spellcheck.yaml b/.github/workflows/spellcheck.yaml index f1948889..cacb017c 100644 --- a/.github/workflows/spellcheck.yaml +++ b/.github/workflows/spellcheck.yaml @@ -2,10 +2,10 @@ name: 'Check spelling' on: # rebuild any PRs and main branch changes push: branches: - - 1.0.0* + - 1.0* pull_request: branches: - - 1.0.0* + - 1.0* jobs: spellcheck: # run the action diff --git a/.gitignore b/.gitignore index 3c8fa767..40bc5fc7 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,4 @@ -docs/openapi.yaml +docs/openapi-1.0.yaml _site/ .sass-cache/ .jekyll-cache/ diff --git a/.redocly.lint-ignore.yaml b/.redocly.lint-ignore.yaml index 1b8846d2..237be605 100644 --- a/.redocly.lint-ignore.yaml +++ b/.redocly.lint-ignore.yaml @@ -1,6 +1,6 @@ # This file instructs Redocly's linter to ignore the rules contained for specific parts of your API. # See https://redoc.ly/docs/cli/ for more information. -docs/openapi.yaml: +docs/openapi-1.0.yaml: no-unused-components: # the created response's headers are used but # since the bodies are not empty, the entire diff --git a/.spectral.yaml b/.spectral.yaml index f818751f..9dad7b3c 100644 --- a/.spectral.yaml +++ b/.spectral.yaml @@ -60,6 +60,6 @@ overrides: # and to keep the individual responses DRY, we want # to keep the 201 in the root openapi file, so we # disable the unused component rule for this response - - "docs/openapi.yaml#/components/responses/201" + - "docs/openapi-1.0.yaml#/components/responses/201" rules: oas3-unused-component: "off" diff --git a/.vscode/settings.json b/.vscode/settings.json index 8be1c56e..566e2a14 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -11,6 +11,6 @@ }, "spectral.rulesetFile": ".spectral.yaml", "spectral.validateFiles": [ - "**/docs/openapi.yaml" + "**/docs/openapi-1.0.yaml" ] } \ No newline at end of file diff --git a/docs/_config.yml b/docs/_config.yml index bdf066a0..166e4023 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -25,7 +25,7 @@ aux_links: - "https://github.com/TROLIE/spec" "OpenAPI Specification": - - "/spec" + - "/spec-1.0" compress_html: ignore: @@ -51,7 +51,7 @@ callouts: gh_edit_link: true gh_edit_link_text: "Edit this page on GitHub" gh_edit_repository: "https://github.com/TROLIE/spec" -gh_edit_branch: "1.0.0-wip" +gh_edit_branch: "1.0" gh_edit_source: docs gh_edit_view_mode: "tree" diff --git a/docs/_spec/openapi-split.yaml b/docs/_spec/openapi-split.yaml index a3f636d1..cea40f7c 100644 --- a/docs/_spec/openapi-split.yaml +++ b/docs/_spec/openapi-split.yaml @@ -52,7 +52,7 @@ info: Primary Interactions with Ratings Provider - version: 1.0.0-wip-realtime-stable + version: 1.0.0 contact: name: TROLIE Maintainers email: maintainers@trolie.energy diff --git a/docs/articles/RC-to-RC-reconciliation.md b/docs/articles/RC-to-RC-reconciliation.md index 16ebe215..931c2d1b 100644 --- a/docs/articles/RC-to-RC-reconciliation.md +++ b/docs/articles/RC-to-RC-reconciliation.md @@ -32,13 +32,13 @@ ratings independently, GLRs for these facilities must be resolved after clearing In terms of TROLIE mechanics, the initial output of each RC's clearinghouse is considered the [Regionally Limiting Rating](../concepts.md#regionally-limiting-rating) or RLR. Peer TROLIEs can continuously poll each other for new RLRs using the -[getRegionalLimitsForecastSnapshot](../spec#tag/Forecasting/operation/getRegionalLimitsForecastSnapshot) +[getRegionalLimitsForecastSnapshot](../spec-1.0#tag/Forecasting/operation/getRegionalLimitsForecastSnapshot) operation. After receiving RLRs from all neighbors in addition to generating its own, the TROLIE instance can generate a regular snapshot that consists of [Globally Limiting Ratings](../concepts.md#globally-limiting-rating) or GLRs, that incorporate the most conservative RLRs for each facility. Only these GLR snapshots should be visible via -[getLimitsForecastSnapshot](../spec#tag/Forecasting/operation/getLimitsForecastSnapshot), which represents the final +[getLimitsForecastSnapshot](../spec-1.0#tag/Forecasting/operation/getLimitsForecastSnapshot), which represents the final ratings that may be used in key decisions such as markets, look-ahead unit commitment and dispatch, and outage coordination. @@ -78,7 +78,7 @@ sequenceDiagram Each of the steps above deserves some more context. The following listing describes each event, referencing the sequence numbers in the diagram above: -1. The RC TROLIE server needs to poll for new RLRs against Neighbor RC 1. This leverages the [Conditional GET](./conditional-GET.md) pattern, against [getRegionalLimitsForecastSnapshot](../spec#tag/Forecasting/operation/getRegionalLimitsForecastSnapshot). +1. The RC TROLIE server needs to poll for new RLRs against Neighbor RC 1. This leverages the [Conditional GET](./conditional-GET.md) pattern, against [getRegionalLimitsForecastSnapshot](../spec-1.0#tag/Forecasting/operation/getRegionalLimitsForecastSnapshot). 2. Same as #1 for Neighbor RC 2 3. Same as #1 for Neighbor RC 3 4. Ratings Providers submit proposals, or [LLRs](../concepts.md#locally-limiting-rating), to TROLIE to be processed by the clearinghouse. @@ -97,7 +97,7 @@ Real-time however is more of an eventually consistent flow, constantly convergin there is no "target" window for a given rating. Rather, the value of the rating in use _now_ is constantly being updated, based on the best knowledge a given RC has about the RLRs of the other RC. Like forecast, there is a dedicated operation -[getRegionalRealTimeLimits](../spec#tag/Real-Time/operation/getRegionalRealTimeLimits) to facilitate +[getRegionalRealTimeLimits](../spec-1.0#tag/Real-Time/operation/getRegionalRealTimeLimits) to facilitate polling by the peers. However, rather than wait for new RLR values, the clearinghouse can immediately generate new GLRs. @@ -149,4 +149,4 @@ thorough functional validations that multiple TROLIEs are configured and behavin correctly. Specifically, the following conditions must be true: * Since both TROLIEs are generating seam monitoring sets, these monitoring sets should represent the same set of resources. The monitoring sets should have the same size, and each resource should have an alias that maps to the primary identifier or one of the aliases in the other monitoring set. -* For a given forecast window, the result of [getLimitsForecastSnapshot](../spec#tag/Forecasting/operation/getLimitsForecastSnapshot) (the GLRs) should be identical in each TROLIE. \ No newline at end of file +* For a given forecast window, the result of [getLimitsForecastSnapshot](../spec-1.0#tag/Forecasting/operation/getLimitsForecastSnapshot) (the GLRs) should be identical in each TROLIE. \ No newline at end of file diff --git a/docs/articles/limit-provenance.md b/docs/articles/limit-provenance.md index 2fbbedb0..330233c1 100644 --- a/docs/articles/limit-provenance.md +++ b/docs/articles/limit-provenance.md @@ -33,8 +33,8 @@ Taken together, we refer to this information as the provenance of the limit. ## How TROLIE Represents Provenance {:.no_toc} -Whether you are obtaining a [Real-Time](../spec#tag/Real-Time/operation/getRealTimeLimits) -or [Forecast Limits Snapshot](../spec#tag/Forecasting/operation/getLimitsForecastSnapshot), +Whether you are obtaining a [Real-Time](../spec-1.0#tag/Real-Time/operation/getRealTimeLimits) +or [Forecast Limits Snapshot](../spec-1.0#tag/Forecasting/operation/getLimitsForecastSnapshot), TROLIE specifies a detailed [media type](./media-types.md) that contains provenance information; these are * `application/vnd.trolie.realtime-limits-detailed-snapshot.v1+json` and @@ -109,8 +109,8 @@ for a given power system resource. See [Conditional Ratings](../decision-log/con Similarly, the `source` object refers to the original Ratings Proposal message that contained this proposal. This is exactly the same information as is contained by `proposal-header.source` -when submitting a [forecast](../spec#tag/Forecasting/operation/patchRatingForecastProposal) -or [real-time proposal](../spec#tag/Real-Time/operation/postRealTimeProposal). +when submitting a [forecast](../spec-1.0#tag/Forecasting/operation/patchRatingForecastProposal) +or [real-time proposal](../spec-1.0#tag/Real-Time/operation/postRealTimeProposal). Next we have `proposal-disposition`. This field is an enumeration of two values: `Used` or `Rejected`. In context, this means either this proposal was diff --git a/docs/articles/media-types.md b/docs/articles/media-types.md index cd3074ad..8bd4216b 100644 --- a/docs/articles/media-types.md +++ b/docs/articles/media-types.md @@ -71,7 +71,7 @@ curl -X GET \ | `/limits/realtime-snapshot` | `application/vnd.trolie.realtime-limits-detailed-snapshot.v1+json` | Same as above but add details about how the limit were determined, including the ratings proposals that were considered. | **Note:** the [TROLIE -spec](../spec#tag/Forecasting/operation/getLimitsForecastSnapshot) shows these +spec](../spec-1.0#tag/Forecasting/operation/getLimitsForecastSnapshot) shows these media type options in two places for successful responses: the examples sidebar and the response schema section. diff --git a/docs/articles/peer-monitoring-sets.md b/docs/articles/peer-monitoring-sets.md index 9c297193..6b72393e 100644 --- a/docs/articles/peer-monitoring-sets.md +++ b/docs/articles/peer-monitoring-sets.md @@ -37,8 +37,8 @@ TROLIE servers can mitigate some of this complexity by introspecting monitoring sets. The Venn diagram below illustrates two [monitoring sets](../concepts.md#monitoring-sets) owned by RCs (A and B), one in each of the other's TROLIE servers. Each RC must coordinate creation of monitoring sets in the other's TROLIE in order to monitor ratings, as described in the operations -[getLimitsForecastSnapshot](../spec#tag/Forecasting/operation/getLimitsForecastSnapshot) and -[getRealTimeLimits](../spec#tag/Real-Time/operation/getRealTimeLimits). +[getLimitsForecastSnapshot](../spec-1.0#tag/Forecasting/operation/getLimitsForecastSnapshot) and +[getRealTimeLimits](../spec-1.0#tag/Real-Time/operation/getRealTimeLimits). ![Peers](../images/Seam.excalidraw.png) @@ -53,7 +53,7 @@ The RC A TROLIE can gain insight by specifically being aware of the monitoring s RC B is using to monitor RC A's footprint. This will be referred to as `B-out` in the following examples. Visibility into the monitoring set itself in either system is exposed via the -[getMonitoringSet](../spec#tag/Monitoring-Sets/operation/getMonitoringSet) operation. Given this capability, +[getMonitoringSet](../spec-1.0#tag/Monitoring-Sets/operation/getMonitoringSet) operation. Given this capability, TROLIE for RC A may do the following: * Automatically determine the overlapping aliases between models. @@ -120,7 +120,7 @@ Using monitoring set reconciliation however, any unique identifier may be shared one of the RCs maintaining an alias. Alternatively, RCs that are using ICCP for real-time communications must already coordinate point names for sending the ratings. Using the point name as one of the aliases allows it to be reused to map resources. Consider the following example contents for monitoring sets -as returned by [getMonitoringSet](../spec#tag/Monitoring-Sets/operation/getMonitoringSet) for `B-in` and `B-out` +as returned by [getMonitoringSet](../spec-1.0#tag/Monitoring-Sets/operation/getMonitoringSet) for `B-in` and `B-out` respectively. Note these examples are oversimplified for readability, as they both only contain a single resource: **`B-in`**: diff --git a/docs/articles/tradeoffs.md b/docs/articles/tradeoffs.md index 25b03993..641cbc05 100644 --- a/docs/articles/tradeoffs.md +++ b/docs/articles/tradeoffs.md @@ -45,7 +45,7 @@ design. ## Schema Design Rationale The entire schema for [Forecast -Proposals](https://trolie.energy/spec#tag/Forecasting/operation/patchRatingForecastProposal) +Proposals](https://trolie.energy/spec-1.0#tag/Forecasting/operation/patchRatingForecastProposal) is certain worth scrutinizing, but for our immediate purposes, let's dilate on just the `ratings` object of the message. diff --git a/docs/community-events/20240330-Forecasting-API-stable.md b/docs/community-events/20240330-Forecasting-API-stable.md index 15c11d48..f1bba295 100644 --- a/docs/community-events/20240330-Forecasting-API-stable.md +++ b/docs/community-events/20240330-Forecasting-API-stable.md @@ -9,7 +9,7 @@ parent: Community Events -The specification of the [Forecasting operations](/spec#tag/Forecasting) in +The specification of the [Forecasting operations](/spec-1.0#tag/Forecasting) in TROLIE OpenAPI specification is now considered stable, closing the [associated milestone](https://github.com/trolie/spec/milestone/1). Specifically, no further changes are anticipated to the media type schemas and resource semantics--the diff --git a/docs/community-events/20240701-RealTime-API-stable.md b/docs/community-events/20240701-RealTime-API-stable.md index 40effaab..5c051cc7 100644 --- a/docs/community-events/20240701-RealTime-API-stable.md +++ b/docs/community-events/20240701-RealTime-API-stable.md @@ -9,7 +9,7 @@ parent: Community Events -The specification of the [Real-Time Operations](/spec#tag/Real-Time) in +The specification of the [Real-Time Operations](/spec-1.0#tag/Real-Time) in TROLIE OpenAPI specification is now considered stable, closing the [associated milestone](https://github.com/trolie/spec/milestone/2). Specifically, no further changes are anticipated to the media type schemas and resource semantics--the diff --git a/docs/community-events/20240118-Pulling-into-the-Station.md b/docs/community-events/20241018-Pulling-into-the-Station.md similarity index 95% rename from docs/community-events/20240118-Pulling-into-the-Station.md rename to docs/community-events/20241018-Pulling-into-the-Station.md index fe232bb3..e0db1e5d 100644 --- a/docs/community-events/20240118-Pulling-into-the-Station.md +++ b/docs/community-events/20241018-Pulling-into-the-Station.md @@ -19,13 +19,13 @@ Since our last [Community Post](../community_events.md), we've accomplished a lo * Defined [RC-to-RC rating reconciliation](../articles/RC-to-RC-reconciliation.md) and the underlying [monitoring set reconciliation pattern](../articles/peer-monitoring-sets.md) - which utilizes the affordances for [reading monitoring sets](https://trolie.energy/spec#tag/Monitoring-Sets) + which utilizes the affordances for [reading monitoring sets](https://trolie.energy/spec-1.0#tag/Monitoring-Sets) * Defined a ["slim" media type pattern](../articles/media-types.md#slim-media-types) that optimizes the most common ratings and limits exchanges -* Defined operations for [temporary AAR exceptions](https://trolie.energy/spec#tag/Temporary-AAR-Exceptions) - and [seasonal overrides](https://trolie.energy/spec#tag/Seasonal-Overrides) +* Defined operations for [temporary AAR exceptions](https://trolie.energy/spec-1.0#tag/Temporary-AAR-Exceptions) + and [seasonal overrides](https://trolie.energy/spec-1.0#tag/Seasonal-Overrides) * Incorporated myriad fixes and documentation improvements based on reviews with vendors. @@ -51,7 +51,7 @@ scenarios. ### Managing Temporary AAR Exceptions and Seasonal Overrides -Quoting the [specification](https://trolie.energy/spec#tag/Seasonal-Overrides): +Quoting the [specification](https://trolie.energy/spec-1.0#tag/Seasonal-Overrides): > A Seasonal Override is an instruction to use a temporary static rating set in > lieu of any concurrent Seasonal Rating for a given segment. diff --git a/docs/community-events/20241115-releasing-1.0.0.md b/docs/community-events/20241115-releasing-1.0.0.md new file mode 100644 index 00000000..f2b4e839 --- /dev/null +++ b/docs/community-events/20241115-releasing-1.0.0.md @@ -0,0 +1,24 @@ +--- +title: 1.0.0 Release +parent: Community Events +--- + +{: .announcement } +Reminder: Join us on Wednesday November 20th, 2024 at 1:30pm ET for the webinar [A Lap Around TROLIE 1.0](https://community.linuxfoundation.org/events/details/lfhq-lf-energy-presents-a-lap-around-trolie-10/)! + +# 1.0.0 Release + +With this release the project is committing to a stable specification and any +modifications will update the version per the [versioning +strategy](../decision-log/media-type-versioning.md), but there will be no +breaking changes going forward in the TROLIE 1.0 project. + +Accordingly, the permanent location for the specification is now +[trolie.energy/spec-1.0](../spec-1.0). (Existing links to +[trolie.energy/spec](../spec) will redirect.) The next phase of the project is +integration and testing of TROLIE implementations, and we anticipate needing +minor updates to the specification. These will not be breaking changes, as stated, +so expect to see the spec version to change accordingly. When all is said and done +the TROLIE 1.0 project's API specification may have a version number of 1.1.8, but +that will be considered TROLIE 1.0. Again, we refer the reader to the [versioning +strategy](../decision-log/media-type-versioning.md) for more details. diff --git a/docs/decision-log/rt-vs-forecast-ratings.md b/docs/decision-log/rt-vs-forecast-ratings.md index 9ab9a3d5..f83b4373 100644 --- a/docs/decision-log/rt-vs-forecast-ratings.md +++ b/docs/decision-log/rt-vs-forecast-ratings.md @@ -116,5 +116,5 @@ rating if no such feed is available. ## Consequences TROLIE real-time operations are defined under the `Real-Time` tag of the TROLIE -[specification](https://trolie.energy/spec#tag/Real-Time). As mentioned above, +[specification](https://trolie.energy/spec-1.0#tag/Real-Time). As mentioned above, TROLIE servers may optionally implement these operations. diff --git a/docs/decision-log/seasonal-ratings-schedule.md b/docs/decision-log/seasonal-ratings-schedule.md index d5ad1776..8e3575fc 100644 --- a/docs/decision-log/seasonal-ratings-schedule.md +++ b/docs/decision-log/seasonal-ratings-schedule.md @@ -78,4 +78,4 @@ Provider's business rules and practices. ## Consequences -Seasonal rating support is implemented in the TROLIE [specification](../spec#tag/Seasonal). +Seasonal rating support is implemented in the TROLIE [specification](../spec-1.0#tag/Seasonal). diff --git a/docs/example-narratives/seasonal-ratings.md b/docs/example-narratives/seasonal-ratings.md index 90957787..91f9be3c 100644 --- a/docs/example-narratives/seasonal-ratings.md +++ b/docs/example-narratives/seasonal-ratings.md @@ -22,7 +22,7 @@ If a Transmission Owner is their own Ratings Provider, they must update their se and send them to their transmission provider at least annually. TROLIE provides the -[patchSeasonalRatingsProposal](../spec#tag/Seasonal/operation/patchSeasonalRatingsProposal) +[patchSeasonalRatingsProposal](../spec-1.0#tag/Seasonal/operation/patchSeasonalRatingsProposal) operation for this purpose. **NOTE: Support for this function is an optional part of the TROLIE specification. Transmission Owners / Rating Providers should check with their transmission provider for the method they specifically support for sending seasonal ratings to the transmission provider.** diff --git a/docs/example-narratives/submitting-forecasts.md b/docs/example-narratives/submitting-forecasts.md index f6c4f3af..fc8fb6f1 100644 --- a/docs/example-narratives/submitting-forecasts.md +++ b/docs/example-narratives/submitting-forecasts.md @@ -23,7 +23,7 @@ APIs in particular ([background](../articles/trolie-for-ems-and-ot)). If a Transmission Owner is their own Ratings Provider, they must regularly send a Ratings Forecast to their Transmission Provider. TROLIE provides the -[patchRatingForecastProposal](../spec#tag/Forecasting/operation/patchRatingForecastProposal) +[patchRatingForecastProposal](../spec-1.0#tag/Forecasting/operation/patchRatingForecastProposal) operation for this purpose. @@ -102,7 +102,7 @@ there are other client errors that are not tolerated, including: * Unprocessable content error: when none of the individual resource Forecast Proposals are valid, but the request is otherwise well-formed. -Additional client errors are identified in the [patchRatingForecastProposal spec](../spec#tag/Forecasting/operation/patchRatingForecastProposal). +Additional client errors are identified in the [patchRatingForecastProposal spec](../spec-1.0#tag/Forecasting/operation/patchRatingForecastProposal). ### Clients Should Check the `incomplete-obligation-count` {:.no_toc} diff --git a/docs/example-narratives/submitting-realtime-ratings.md b/docs/example-narratives/submitting-realtime-ratings.md index 731bfa0c..ac01687a 100644 --- a/docs/example-narratives/submitting-realtime-ratings.md +++ b/docs/example-narratives/submitting-realtime-ratings.md @@ -17,7 +17,7 @@ on [forecast](submitting-forecasts) ratings may be helpful for background. If a Transmission Owner is their own Ratings Provider, they must regularly send real-time ratings to their Transmission Provider. TROLIE provides the -[postRealTimeProposal](../spec#tag/Real-Time/operation/postRealTimeProposal) +[postRealTimeProposal](../spec-1.0#tag/Real-Time/operation/postRealTimeProposal) operation for this purpose. @@ -77,7 +77,7 @@ may also consider obligations for resources that would normally not have their ratings submitted as TROLIE proposals, but rather through other means, such as ICCP. Therefore, clients should rely more on asynchronous use of -[getRealTimeProposalStatus](../spec#tag/Real-Time/operation/getRealTimeProposalStatus) +[getRealTimeProposalStatus](../spec-1.0#tag/Real-Time/operation/getRealTimeProposalStatus) as a way to monitor whether the Clearinghouse considers their ongoing data stream healthy. diff --git a/docs/example-narratives/temporary-ratings.md b/docs/example-narratives/temporary-ratings.md index 92f77b3c..64258574 100644 --- a/docs/example-narratives/temporary-ratings.md +++ b/docs/example-narratives/temporary-ratings.md @@ -23,9 +23,9 @@ TROLIE includes two kinds of temporary ratings objects: Temporary ratings, whether they be Temporary AAR Exceptions or Seasonal Overrides, are created in much the same manner. The following `input.json` example could be used to create either a Temporary AAR Exception or Seasonal Override either by invoking -[createTemporaryAARException](../spec#tag/Temporary%20AAR%20Exceptions/operation/createTemporaryAARException) +[createTemporaryAARException](../spec-1.0#tag/Temporary%20AAR%20Exceptions/operation/createTemporaryAARException) or -[createSeasonalOverride](../spec#tag/Seasonal%20Overrides/operation/createSeasonalOverride) +[createSeasonalOverride](../spec-1.0#tag/Seasonal%20Overrides/operation/createSeasonalOverride) respectively: ```json @@ -62,7 +62,7 @@ is given below: Once created, the temporary ratings may be updated. This is often needed if the anticipated end time changes, or if more detail needs to be added to the reason. For the Temporary AAR Exception created above, this may be achieved by -invoking [updateTemporaryAARException](../spec#tag/Temporary%20AAR%20Exceptions/operation/updateTemporaryAARException). +invoking [updateTemporaryAARException](../spec-1.0#tag/Temporary%20AAR%20Exceptions/operation/updateTemporaryAARException). Assuming the `output.json` file above was modified as desired, the Temporary AAR Exception may be updated with the following command. Note that the ID @@ -78,7 +78,7 @@ curl -d @output.json \ Finally, the temporary rating may also have been created by mistake. As long as it hasn't started yet, it may be deleted it using -[deleteTemporaryAARException](../spec#tag/Temporary%20AAR%20Exceptions/operation/deleteTemporaryAARException) +[deleteTemporaryAARException](../spec-1.0#tag/Temporary%20AAR%20Exceptions/operation/deleteTemporaryAARException) This can be done with the following command: ```bash @@ -92,9 +92,9 @@ end time to the current time. ## Searching for Temporary Ratings Temporary ratings that have been submitted to TROLIE may be searched, using either -[getTemporaryAARExceptions](../spec#tag/Temporary%20AAR%20Exceptions/operation/getTemporaryAARExceptions) +[getTemporaryAARExceptions](../spec-1.0#tag/Temporary%20AAR%20Exceptions/operation/getTemporaryAARExceptions) or -[getSeasonalOverrides](../spec#tag/Seasonal%20Overrides/operation/getSeasonalOverrides). These +[getSeasonalOverrides](../spec-1.0#tag/Seasonal%20Overrides/operation/getSeasonalOverrides). These queries may be filtered with query parameters, including start/end time windows, monitoring sets and individual resources. diff --git a/docs/example-narratives/using-slim-media-types.md b/docs/example-narratives/using-slim-media-types.md index 9c26d8cb..35aa09ac 100644 --- a/docs/example-narratives/using-slim-media-types.md +++ b/docs/example-narratives/using-slim-media-types.md @@ -28,7 +28,7 @@ parameter. * `undervoltage-threshold-pu` * `undervoltage-threshold` -These correspond to the valid [Limit Types](../spec#tag/limit-type). +These correspond to the valid [Limit Types](../spec-1.0#tag/limit-type). Here's an example that requests a slim forecast limits snapshot ```http @@ -55,7 +55,7 @@ new header field hours with the assumption that the begins header is the first entry and each subsequent entry represents the subsequent hour's forecast. This is discussed in further detail in the -[spec](../spec#schema/seasonal-proposals-slim). Here we can breakdown a concrete +[spec](../spec-1.0#schema/seasonal-proposals-slim). Here we can breakdown a concrete example. We'll start with a `curl` request, then discuss the HTTP request itself in two parts, the headers then the JSON payload. @@ -75,7 +75,7 @@ curl -X PATCH \ > required by the TROLIE specification for the > `application/vnd.trolie.seasonal-ratings-proposal-slim.v1+json` media type, as > no default `limit-type` can be assumed. See [Limit -> Types](../spec#tag/limit-type) for the other options defined in the spec. +> Types](../spec-1.0#tag/limit-type) for the other options defined in the spec. {: .nb } > The `Accept` header in this example specifies one of the @@ -130,7 +130,7 @@ Content-Type: application/vnd.trolie.seasonal-ratings-proposal-slim.v1+json; lim // note all values are assumed to be MVA because the header in this example // Content-Type: application/vnd.trolie.seasonal-ratings-proposal-slim.v1+json; limit-type=apparent-power // specifies the apparent-power limit type which has a single value of MVA - // see https://trolie.energy/spec#tag/limit-type + // see https://trolie.energy/spec-1.0#tag/limit-type [ // resource-id: 8badf00d [ // season-name: WINTER diff --git a/docs/index.md b/docs/index.md index bc6b67fd..8209b25b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -20,11 +20,11 @@ class="fa-solid fa-envelope">](https://lists.lfenergy.org/g/trolie-general). {: .announcement } -> **Latest Updates** -> -> Join us on Wednesday November 20th, 2024 at 1:30pm ET for the webinar [A Lap Around TROLIE 1.0](https://community.linuxfoundation.org/events/details/lfhq-lf-energy-presents-a-lap-around-trolie-10/)! +> **Latest Updates** 📢 +> +> [TROLIE 1.0.0 is released](./community-events/20241115-releasing-1.0.0)! 🎉 > -> Read more in the [latest status update](./community-events/20240118-Pulling-into-the-Station.md). +> Join us on Wednesday November 20th, 2024 at 1:30pm ET for the webinar [A Lap Around TROLIE 1.0](https://community.linuxfoundation.org/events/details/lfhq-lf-energy-presents-a-lap-around-trolie-10/)! # Introduction @@ -44,11 +44,12 @@ will help accelerate their implementation and simplify interoperability. The project’s specific aims are: -* In Progress: Define an API specification +* ✅ Define an API specification for the exchange of ratings and ratings-related information to support organizations working to comply with FERC Order 881. -* TODO: A conformance program to +* In Progress: A [conformance + program](https://github.com/trolie/conformance) to provide vendors a means to demonstrate their compatibility with the above specification and signal their commitment to maintaining compatibility. diff --git a/docs/spec.html b/docs/spec-1.0.html similarity index 93% rename from docs/spec.html rename to docs/spec-1.0.html index b17e5d47..fbb3c48c 100644 --- a/docs/spec.html +++ b/docs/spec-1.0.html @@ -22,7 +22,7 @@ - + \ No newline at end of file diff --git a/docs/spec.md b/docs/spec.md new file mode 100644 index 00000000..98160e73 --- /dev/null +++ b/docs/spec.md @@ -0,0 +1,3 @@ +--- +redirect_to: spec-1.0 +--- \ No newline at end of file diff --git a/redocly.yaml b/redocly.yaml index 461fb8c9..e95f3c2b 100644 --- a/redocly.yaml +++ b/redocly.yaml @@ -15,4 +15,4 @@ apis: trolie@dev: root: ./docs/_spec/openapi-split.yaml trolie@v1: - root: ./docs/openapi.yaml + root: ./docs/openapi-1.0.yaml