diff --git a/cspell.json b/cspell.json index 7e648c1..c544a0b 100644 --- a/cspell.json +++ b/cspell.json @@ -6,18 +6,19 @@ "dictionaryDefinitions": [], "dictionaries": [], "words": [ - "devcontainer", - "excalidraw", - "FERC", - "ICCP", - "NERC", - "openapi", - "owasp", - "redoc", - "Redocly", - "ruleset", - "TROLIE", - "Vernova" + "devcontainer" + ,"excalidraw" + ,"FERC" + ,"ICCP" + ,"NERC" + ,"openapi" + ,"owasp" + ,"redoc" + ,"Redocly" + ,"ruleset" + ,"TROLIE" + ,"Vernova" + ,"SCADA" ], "ignoreWords": [], "import": [] diff --git a/docs/_config.yml b/docs/_config.yml index 886b0b5..cf67e9a 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -22,3 +22,12 @@ aux_links: "OpenAPI Specification": - "/spec" + +compress_html: + ignore: + envs: all + +kramdown: + syntax_highlighter_opts: + block: + line_numbers: true \ No newline at end of file diff --git a/docs/_data/components/schemas/limit-provenance.yaml b/docs/_data/components/schemas/limit-provenance.yaml index 80c0086..46963e7 100644 --- a/docs/_data/components/schemas/limit-provenance.yaml +++ b/docs/_data/components/schemas/limit-provenance.yaml @@ -24,8 +24,8 @@ properties: reason itself. If not provided, users may assume no override is in place. - allOf: - - $ref: '../../openapi-split.yaml#/components/schemas/description' + format: free-text + maxLength: 500 additional-data: description: > Implementors may use this object to provide freeform extensions with diff --git a/docs/_data/components/schemas/naming-scheme-set.yaml b/docs/_data/components/schemas/naming-scheme-set.yaml index c992fa8..0928566 100644 --- a/docs/_data/components/schemas/naming-scheme-set.yaml +++ b/docs/_data/components/schemas/naming-scheme-set.yaml @@ -9,6 +9,6 @@ items: $ref: ./generic-identifier.yaml description: type: string + format: free-text + maxLength: 500 example: Asset registration system identifiers - allOf: - - $ref: '../../openapi-split.yaml#/components/schemas/description' diff --git a/docs/_data/openapi-split.yaml b/docs/_data/openapi-split.yaml index 32dbf77..e783b1b 100644 --- a/docs/_data/openapi-split.yaml +++ b/docs/_data/openapi-split.yaml @@ -90,7 +90,7 @@ info: name: Apache License, Version 2.0 url: https://www.apache.org/licenses/LICENSE-2.0 servers: - - url: https://no-server/trolie + - url: https://trolie.example.com tags: - name: Monitoring Sets description: > @@ -412,21 +412,6 @@ components: pattern: ^$ example: "" - hash: - type: string - description: A hex encoded hash value as produced by, e.g., SHA512. - maxLength: 256 - pattern: ^[A-Fa-f0-9\-]{6,256}$ - example: >- - 8f27c691ded1634cc83491368203c7d2af782d45a7375b49d6e6b042132ee48b9c78fb6a4a274f118a8bd97abe40305e6a0598c694fa5dee6eb70e750fd617e3 - - origin-id: - description: Opaque correlation identifier assigned by the originating system. - type: string - maxLength: 50 - pattern: ^(.){1,50}$ - example: fded654c-64f5-4db9-9467-8937d2b3f027 - problem: description: See [RFC9457](https://www.rfc-editor.org/rfc/rfc9457#appendix-A). type: object @@ -466,16 +451,17 @@ components: headers: ETag: description: > - An opaque, unique identifier for a specific version of a resource. The modeled - resource state is what is versioned, not the content of any particular - representation. The server MUST use a strong validator so that the same ETag - is returned regardless of the media type of the representation. + An opaque, unique identifier--typically a hash value--for a specific + version of a resource. The modeled resource state is what is versioned, + not the content of any particular representation. The server MUST use a + strong validator so that the same ETag is returned regardless of the + media type of the representation. schema: type: string + format: hash + maxLength: 256 additionalProperties: false - anyOf: - - $ref: "#/components/schemas/hash" - - $ref: "#/components/schemas/origin-id" + X-Rate-Limit-Limit: description: The number of allowed requests in the current period schema: diff --git a/docs/_data/paths/limits_forecast-snapshot.yaml b/docs/_data/paths/limits_forecast-snapshot.yaml index 619c926..d3861b7 100644 --- a/docs/_data/paths/limits_forecast-snapshot.yaml +++ b/docs/_data/paths/limits_forecast-snapshot.yaml @@ -42,12 +42,12 @@ get: schema: $ref: "../components/schemas/array-max-monitored-elements.yaml#/forecast-limit-set" example: - $ref: '../../examples/forecast-limits-slim.json' + $ref: '../../example-narratives/examples/forecast-limits-slim.json' application/vnd.trolie.forecast-limit-set-detailed.v1+json: schema: $ref: "../components/schemas/array-max-monitored-elements.yaml#/forecast-limit-set-detailed" example: - $ref: "../../examples/forecast-limits-detailed.json" + $ref: "../../example-narratives/examples/forecast-limits-detailed.json" application/json: schema: $ref: "../components/schemas/array-max-monitored-elements.yaml#/forecast-limit-set" diff --git a/docs/_data/paths/limits_forecast-snapshot_period_{period-start}.yaml b/docs/_data/paths/limits_forecast-snapshot_period_{period-start}.yaml index 5a9ea7c..7645f23 100644 --- a/docs/_data/paths/limits_forecast-snapshot_period_{period-start}.yaml +++ b/docs/_data/paths/limits_forecast-snapshot_period_{period-start}.yaml @@ -32,7 +32,7 @@ get: schema: $ref: "../components/schemas/array-max-monitored-elements.yaml#/forecast-limit-set" example: - $ref: "../../examples/forecast-limits-slim.json" + $ref: "../../example-narratives/examples/forecast-limits-slim.json" application/vnd.trolie.forecast-limit-set-detailed.v1+json: schema: $ref: "../components/schemas/array-max-monitored-elements.yaml#/forecast-limit-set-detailed" diff --git a/docs/_data/paths/limits_realtime-snapshot.yaml b/docs/_data/paths/limits_realtime-snapshot.yaml index 4c5a670..ef33898 100644 --- a/docs/_data/paths/limits_realtime-snapshot.yaml +++ b/docs/_data/paths/limits_realtime-snapshot.yaml @@ -31,12 +31,12 @@ get: schema: $ref: "../components/schemas/array-max-monitored-elements.yaml#/realtime-limit-set" example: - $ref: '../../examples/realtime-limit-set-slim.json' + $ref: '../../example-narratives/examples/realtime-limit-set-slim.json' application/vnd.trolie.realtime-limit-set-detailed.v1+json: schema: $ref: "../components/schemas/array-max-monitored-elements.yaml#/realtime-limit-set-detailed" example: - $ref: '../../examples/realtime-limit-set-detailed.json' + $ref: '../../example-narratives/examples/realtime-limit-set-detailed.json' application/json: schema: $ref: "../components/schemas/array-max-monitored-elements.yaml#/realtime-limit-set" diff --git a/docs/_data/paths/rating-proposals_forecasts.yaml b/docs/_data/paths/rating-proposals_forecasts.yaml index 3355585..1081445 100644 --- a/docs/_data/paths/rating-proposals_forecasts.yaml +++ b/docs/_data/paths/rating-proposals_forecasts.yaml @@ -94,23 +94,7 @@ patch: schema: $ref: ../components/schemas/forecast-rating-proposal.yaml example: - ratings: - - segment-id: segmentX - periods: - - period-start: '2023-07-12T16:00:00-07:00' - values: - - type: normal - value: - mva: 160 - - type: ste - value: - mva: 165 - - type: lte - value: - mva: 170 - - type: dal - value: - mva: 170 + $ref: ../../example-narratives/examples/forecast-ratings-proposal-patch.json application/json: schema: $ref: ../components/schemas/forecast-rating-proposal.yaml diff --git a/docs/concepts.md b/docs/concepts.md new file mode 100644 index 0000000..8bbb10b --- /dev/null +++ b/docs/concepts.md @@ -0,0 +1,25 @@ +--- +title: TROLIE Concepts +nav_order: 3 +--- + +# TROLIE Concepts + +Before reviewing examples, users may benefit from a basic understanding of the key constructs used by the TROLIE APIs. Definitions of these concepts are included here. + +## Transmission Facilities +A Transmission Facility is a logical part of the electrical network that may have a rating, whether simply seasonal or an AAR. This most often represents a transmission line, but could also include transformers and other large pieces of equipment, or perhaps even logical points on the network such as interfaces. Most importantly, these are points at which transmission providers need rating values to operate against. + +Rating snapshots are always done against Transmission Facilities. Transmission Facilities include one or more Segments. The Transmission Facilities included in TROLIE are typically pre-coordinated ahead of time, often through a modeling process. + +## Segments +Segments represent a component of some Transmission Facility that may affect its overall rating. All Transmission Facilities must have at least one Segment. In terms of TROLIE, ratings providers are obligated to provide rating data, in the form of Proposals, against segments. On jointly owned lines or tie lines for example, each stakeholder in the line (the Transmission Facility) will be responsible for submitting Proposals against a different Segment in the model allocated to that stakeholder. + +## Proposals +Proposals are forecasted or real-time ratings values submitted to TROLIE against a particular Segment. They are referred to as "Proposals", as they are inputs to the limit "clearing" process internal to TROLIE server implementations that will integrate them into a final in-use rating set. In-use limit Snapshots are a distinct data set from Proposals. Proposals may be queried as well as submitted, so that the rating provider's original input data is always kept separately from the in-use ratings. + +## Snapshots +As implied above, Snapshots are generated in TROLIE server implementations based on proposals and other inputs to generate in-use ratings for each Transmission Facility. TROLIE allows for ratings providers to fetch the latest snapshot, aka the latest "version" of the ratings data. + +## Monitoring Sets +Monitoring Sets are arbitrarily defined sets of transmission facilities that may be used to filter ratings and limits returned by queries against these APIs. Defining the contents of these monitoring sets may vary, and is up to TROLIE server implementations. diff --git a/docs/daylight-savings.md b/docs/daylight-savings.md new file mode 100644 index 0000000..44051e0 --- /dev/null +++ b/docs/daylight-savings.md @@ -0,0 +1,25 @@ +--- +title: Daylight Savings +nav_order: 5 +--- + +# Handling Daylight Savings Transitions in TROLIE + +Daylight savings transitions are a notorious problem in software systems. Specifically in data exchanges, data formats must contend with two challenges: + +* Both transition days don't have 24 hours. The Spring transition of course has 23, the Fall transition 25. +* The day of the Fall transition has two unique hours that are both referred to in local clocks as "1 AM", one before and the other after the transition. + +The first problem (non-24 hour days) does not create any particular problem for the TROLIE data formats. The second problem of the "duplicate hour" however is explicitly handled by the consistent use of the standard [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) date time format. This format assumes that the server can understand time universally, typically by using internal references in UTC. In the API, RFC 3339 date times must include explicit operating time zone offsets from UTC. Therefore, the difference between the "1 AM" hours is always visible in the timezone offset. + +For example, in central US time in 2025, the Fall transition day would begin with the following hours: + +{% highlight none %} +2025-11-02T00:00:00-05:00 +2025-11-02T01:00:00-05:00 +2025-11-02T01:00:00-06:00 +2025-11-02T02:00:00-06:00 +2025-11-02T03:00:00-06:00 +{% endhighlight %} + +Note that the two 01:00:00 times are uniquely distinguished with the -05:00 and -06:00 offsets. \ No newline at end of file diff --git a/docs/examples/forecast-limits-detailed.json b/docs/example-narratives/examples/forecast-limits-detailed.json similarity index 100% rename from docs/examples/forecast-limits-detailed.json rename to docs/example-narratives/examples/forecast-limits-detailed.json diff --git a/docs/examples/forecast-limits-slim.json b/docs/example-narratives/examples/forecast-limits-slim.json similarity index 100% rename from docs/examples/forecast-limits-slim.json rename to docs/example-narratives/examples/forecast-limits-slim.json diff --git a/docs/example-narratives/examples/forecast-ratings-proposal-patch.json b/docs/example-narratives/examples/forecast-ratings-proposal-patch.json new file mode 100644 index 0000000..6f75e09 --- /dev/null +++ b/docs/example-narratives/examples/forecast-ratings-proposal-patch.json @@ -0,0 +1,60 @@ +{ + "ratings": [ + { + "segment-id": "segmentX", + "periods": [ + { + "period-start": "2025-11-02T01:00:00-05:00", + "values": [ + { + "type": "normal", + "value": { + "mva": 160 + } + }, + { + "type": "emergency", + "value": { + "mva": 165 + } + } + ] + }, + { + "period-start": "2025-11-02T01:00:00-06:00", + "values": [ + { + "type": "normal", + "value": { + "mva": 162 + } + }, + { + "type": "emergency", + "value": { + "mva": 167 + } + } + ] + }, + { + "period-start": "2025-11-02T02:00:00-06:00", + "values": [ + { + "type": "normal", + "value": { + "mva": 162 + } + }, + { + "type": "emergency", + "value": { + "mva": 167 + } + } + ] + } + ] + } + ] +} \ No newline at end of file diff --git a/docs/examples/realtime-limit-set-detailed.json b/docs/example-narratives/examples/realtime-limit-set-detailed.json similarity index 100% rename from docs/examples/realtime-limit-set-detailed.json rename to docs/example-narratives/examples/realtime-limit-set-detailed.json diff --git a/docs/examples/realtime-limit-set-slim.json b/docs/example-narratives/examples/realtime-limit-set-slim.json similarity index 100% rename from docs/examples/realtime-limit-set-slim.json rename to docs/example-narratives/examples/realtime-limit-set-slim.json diff --git a/docs/example-narratives/in-use-forecasts.md b/docs/example-narratives/in-use-forecasts.md new file mode 100644 index 0000000..4b8672b --- /dev/null +++ b/docs/example-narratives/in-use-forecasts.md @@ -0,0 +1,29 @@ +--- +title: Querying in-use Limit Forecast +parent: Usage Examples +nav_order: 2 +--- + +# Ratings Provider Querying in-use Limit Forecast from the Transmission Provider + +Assuming a MonitoringSet "my-monitoring-set" that contains TransmissionFacilities of interest, then the current in-use forecasted limits may be fetched with the following command: + +```bash +curl -H "Accept: application/vnd.trolie.forecast-limit-set-slim.v1+json" \ +-o output.json \ +"https://trolie.example.com/rating-proposals/forecasts?monitoring-set=my-monitoring-set" +``` + +This will return the current version of the in-use ratings for the next 240 hours into output.json. See the following for an example: + +```json +{% include_relative examples/forecast-limits-slim.json %} +``` + +The above example assumes the next 240 hours as determined by the computer clock where TROLIE server is running. Given that there are edge cases in time and the user’s clocks are likely slightly off from the TROLIE server's clock, it is recommended to specify the times more explicitly to ensure that users are getting what is expected. This may be done by specifying the "offset-period-start" parameter, like in the following example: + +``` +https://trolie.example.com/rating-proposals/forecasts?monitoring-set=my-monitoring-set&offset-period-start=2025-11-02T02:00:00-06:00 +``` + +**NOTE**: This query is an example of an HTTP GET. In addition to curl, the same URL may also be placed in a web browser to see the data. diff --git a/docs/example-narratives/submitting-forecasts.md b/docs/example-narratives/submitting-forecasts.md new file mode 100644 index 0000000..989bf86 --- /dev/null +++ b/docs/example-narratives/submitting-forecasts.md @@ -0,0 +1,28 @@ +--- +title: Submitting Forecast Ratings +parent: Usage Examples +nav_order: 1 +--- + +# Ratings Provider Submitting Forecast Ratings to the Transmission Provider + +For most transmission owners (rating providers in TROLIE terminology), the most important operation will be to regularly (at least hourly) send forecasted AARs to SPP. This is done by updating that TO’s forecasted rating Proposal. More specifically, this may be achieved using the [patchRatingForecastProposal](../spec#tag/Rating-Proposals/operation/patchRatingForecastProposal) operation in TROLIE. + +For the purpose of this example, the JSON listing below may be assumed to be in a file called `input.json`. The input consists of an array by segment, which then contains an array of ratings for each forecast period. Note this example also cross the Fall daylight savings transition in the central timezone, thus providing an example of dealing with the notorious "duplicate" 1 AM hour: + +```json +{% include_relative examples/forecast-ratings-proposal-patch.json %} +``` + +## Pushing input.json to TROLIE +Given input.json, run the following command to send it to the TROLIE server: + +```bash +curl -d @input.json \ +-X PATCH \ +-H "Content-Type: application/vnd.trolie.rating-forecast-proposal.v1+json" \ +-o output.json \ +"https://trolie.example.com/rating-proposals/forecasts" +``` + +On success, output.json will container a copy of the data just uploaded, with additional metadata on update time and status. diff --git a/docs/index.md b/docs/index.md index bea5eb8..51eca05 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,6 @@ --- title: Home +nav_order: 1 --- diff --git a/docs/rest.md b/docs/rest.md new file mode 100644 index 0000000..25f90a0 --- /dev/null +++ b/docs/rest.md @@ -0,0 +1,172 @@ +--- +title: Why REST and OpenAPI? +nav_order: 2 +--- + +# Why REST and OpenAPI? + +While REST isn’t new. It was first published in [academic literature in the +year 2000](https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm). + +However, it may imply a learning curve for typical operations technology (OT) +teams that need to integrate with TROLIE. This is because EMS systems are the +most common integration targets for TROLIE, where older methods have frequently +been used for data exchanges, such as SCADA protocols, custom TCP-based +protocols, and ad-hoc file exchanges. + +TROLIE is built on the philosophy that this is an acceptable tradeoff due to the +upside that REST offers over these traditional data exchange methods. An entire +paper could be written purely on this subject as to the benefits of using REST +for this sort of complex data exchange. To summarize: + +* REST is significantly easier to secure than either SCADA protocols or + file-based exchanges. This aligns well to modern cyber-security architectures, + but also provides several security benefits and architectural flexibility to + transmission providers. It is ultimately a transmission provider's decision + whether to run the API directly over the public internet or over dedicated + channel such as a VPN or frame relay. Nothing in REST requires a dedicated + channel. + +* Data integrity and non-repudiation is much easier to achieve with REST, + especially vs file exchanges. + +* REST has established patterns for modeling complex data structures that would + be awkward in SCADA-style exchanges like ICCP. + +* REST has established patterns for making backward compatibility significantly + easier than it would be for file exchanges without developing complex custom + conventions. + +* It will be significantly easier to scale the system in terms of both load and + performance with REST than it would be with the more traditional exchange + methods used in EMS. + + +While there are many good materials available for understanding the REST +architecture in detail, users of the TROLIE APIs do not need to be experts in +REST. From a user perspective, REST could be seen as a minor cognitive leap +from file exchanges, which this document will illustrate through examples. + +## Why not ICCP? +The Inter-Control Center Communications Protocol (ICCP), part of IEC standard +60870-6, is used frequently to integrate Reliability Coordinators' SCADA system +with member transmission owners' SCADA systems to capture all kinds of telemetry +data from the power grid. It has traditionally been used for dynamic line +ratings / real-time AARs for selected lines as an emerging technology. ICCP +works well for this use case, as the rating of the line in real-time is +functionally much like any other telemetry. ICCP is reliable, mature, and +well-known, and will continue to be supported by many transmission providers as +a method for submitting real-time ratings. Even though TROLIE supports +real-time rating exchange, continued use of ICCP for real-time ratings is +compatible with the use of TROLIE. However, ICCP won’t scale well to handle the +forecasted data. There are a couple reasons for this: + +* The data model is a significant mismatch. ICCP is designed around SCADA + concepts, such as points and quality flags. It is difficult to create + arbitrarily complex data structures, like a coordinated forecast, and link + them together. There are also needs to provide various strings into this + data, such as override reasons. + +* Using ICCP for forecasts would result in a significant increase in the count + of SCADA points. Across our customer base, GE sees increased pressure on + SCADA systems due to other changes to the power grid. The increased + configuration overhead and load on potentially overtaxed SCADA systems makes + ICCP less attractive. + +This is all in addition to considering the advantages of REST discussed above. + +## Why not File Exchanges? + +Unlike ICCP, file exchanges using common formats such as CSV, XML, and JSON do +allow for more complex data structures. The advantages to REST however over +file exchanges are all outlined above. In addition to these more abstract +advantages, the authors of TROLIE see a trend across the utility industry where +file exchanges are becoming a common source of failure and management expense +for backing infrastructure / IT teams. File exchanges, especially over +networks, imply the use of high-end shared storage devices. These devices are +complex to maintain, secure, and operate redundantly across data centers, and +we've seen in practice are a common source of many of the application failures +utilities and other grid operators see in production. + +## REST is a Document Exchange Over the Web + +To understand this API, REST could simply be seen as the exchange of JSON +"files" over HTTP (or more precisely for production environments, HTTPS). +TROLIE API implementers host a server, which may be accessed over the HTTPS port +(443). As a user, one sends a JSON document to a URL, much like a website. +This act of sending, called a "request", includes the following: + +* A URL, much like one would enter a web browser to visit a website. This URL + determines the operation of the API being invoked, as well as identifying + information for the resource being edited. The URL may also include query + parameters. + +* A set of headers. These are key-value pairs that also provide metadata about + the request. + +* A "method" to be used against the resource. Methods are a built-in part of + the HTTP protocol, and the typical standard methods are used by the TROLIE + API. These include: + + - `GET` fetches a resource. `GET`s are generally queries. + + - `HEAD` only fetches HTTP response headers associated with a resource one + would otherwise `GET`. This is for more advanced usage, often associated with + caching. `HEAD` requests may be used to determine whether data returned by + `GET` has changed without calling `GET`. + + - `POST` is used to create a new resource. + + - `PUT` is used to update a resource. + + - `PATCH` is used to partially update a resource. This is like `PUT` but + implies that users don’t have to provide the whole document. Rather, the JSON + document would include only the changes. + + - `DELETE`, intuitively, deletes a resource. + +* A JSON document to be used as input, referred to as a request "body". This is + only applicable for `POST`, `PUT` and `PATCH` requests. + +In return, the server will respond back with a response. The response includes: + +* A numeric status code, indicating success or failure of the request. TROLIE + uses standard HTTP status codes. + +* A set of response headers. These are key-value pairs providing metadata of + the response, much like the request headers. + +* A JSON document, referred to as a response “body”, including either the data + requested, or a list of errors or warnings. Not all operations return bodies. + `HEAD` requests, for example, never return bodies on success. + +While a toolkit is available in most modern languages for executing these +requests in a high-performance way in-memory, it may be convenient for users to +learn the API through file exchange. This is possible using the free +open-source tool [Curl](https://curl.se/). Curl is a command-line tool that may +be used to interact with REST APIs, including TROLIE, entirely using files. +Curl is included with most Linux distributions as well as MacOS. It may be +freely downloaded for Windows from the Curl website linked above. The examples +of usage in [Usage Examples](usage-examples.html) are done entirely using Curl. + +## OpenAPI + +In practice, modern REST APIs are documented using OpenAPI specifications. +These specifications dictate the operations that are available in the API, along +expected parameters, headers, response codes, and JSON schema for requests and +responses. This also includes documentation and descriptions of schema, +operations, and parameters. OpenAPI specifications are specified in files, +formatted using either YAML or JSON. TROLIE provides an OpenAPI specification +using YAML, the more easily human-readable format. + +Many tools are available to work with OpenAPI, both commercial and open source. +A good reference may be found at [here](https://openapi.tools/). Libraries are +available to work with REST and OpenAPI in most programming languages grid +operators are familiar with, including Python, Java, C#/.NET and others. The +TROLIE project recommends ratings providers use these tools to integrate their +systems with TROLIE. + +As mentioned above, it is also possible to simply work with files using curl and +similar utilities. This is recommended to be used primarily for testing and +exploration purposes. Likewise, it is possible to invoke the GET operations of +the API simply by putting the appropriate URLs in a web browser. diff --git a/docs/usage-examples.md b/docs/usage-examples.md new file mode 100644 index 0000000..55538df --- /dev/null +++ b/docs/usage-examples.md @@ -0,0 +1,26 @@ +--- +title: Usage Examples +nav_order: 4 +has_children: true +--- + +# Usage Examples + +These pages run through some simple examples of API usage for typical use cases, +using JSON snippets and [curl](https://curl.se/) commands. + +## Caveats on Examples + +The examples provided here have some limitations, as the real TROLIE server +implementations may differ in certain details: + +* The actual URLs used for the TROLIE service themselves are only examples. + +* Additional configuration will be necessary depending on the authentication + strategy used. This is ultimately a platform capability of the Transmission + Provider and/or vendor implementing the TROLIE server. + +* The rating set tiers (normal, emergency, short-term emergency etc) used by + each Transmission Provider differ, and TROLIE is designed to be agnostic to + this. The rating names therefore used in these examples may not match + exactly those in use by a particular TROLIE server. diff --git a/redocly.yaml b/redocly.yaml index 03e618b..f7963a2 100644 --- a/redocly.yaml +++ b/redocly.yaml @@ -3,6 +3,7 @@ extends: rules: operation-summary: warn + no-server-example.com: off rule/media-type-example-defined: subject: type: MediaType @@ -14,4 +15,4 @@ apis: trolie@dev: root: ./docs/_data/openapi-split.yaml trolie@v1: - root: ./docs/openapi.yaml \ No newline at end of file + root: ./docs/openapi.yaml