diff --git a/cspell.json b/cspell.json
index d98d0994..6a5863ee 100644
--- a/cspell.json
+++ b/cspell.json
@@ -8,6 +8,7 @@
,"./**/*.lock"
,"*.svg"
,"*.puml"
+ ,"docs/_includes/*.html"
],
"dictionaryDefinitions": [],
"dictionaries": [],
diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock
index eda5a441..8c949541 100644
--- a/docs/Gemfile.lock
+++ b/docs/Gemfile.lock
@@ -16,7 +16,7 @@ GEM
addressable (2.8.7)
public_suffix (>= 2.0.2, < 7.0)
base64 (0.2.0)
- benchmark (0.3.0)
+ benchmark (0.4.0)
bigdecimal (3.1.8)
coffee-script (2.4.1)
coffee-script-source
@@ -37,12 +37,12 @@ GEM
ffi (>= 1.15.0)
eventmachine (1.2.7)
execjs (2.10.0)
- faraday (2.12.0)
- faraday-net_http (>= 2.0, < 3.4)
+ faraday (2.12.1)
+ faraday-net_http (>= 2.0, < 3.5)
json
logger
- faraday-net_http (3.3.0)
- net-http
+ faraday-net_http (3.4.0)
+ net-http (>= 0.5.0)
ffi (1.17.0)
forwardable-extended (2.6.0)
gemoji (4.1.0)
@@ -214,7 +214,7 @@ GEM
gemoji (>= 3, < 5)
html-pipeline (~> 2.2)
jekyll (>= 3.0, < 5.0)
- json (2.8.1)
+ json (2.8.2)
just-the-docs (0.10.0)
jekyll (>= 3.8.5)
jekyll-include-cache
@@ -235,7 +235,7 @@ GEM
jekyll-feed (~> 0.9)
jekyll-seo-tag (~> 2.1)
minitest (5.25.1)
- net-http (0.4.1)
+ net-http (0.5.0)
uri
nokogiri (1.16.7-x86_64-linux)
racc (~> 1.4)
@@ -262,7 +262,7 @@ GEM
sawyer (0.9.2)
addressable (>= 2.3.5)
faraday (>= 0.17.3, < 3)
- securerandom (0.3.1)
+ securerandom (0.3.2)
simpleidn (0.2.3)
terminal-table (1.8.0)
unicode-display_width (~> 1.1, >= 1.1.1)
@@ -271,7 +271,7 @@ GEM
tzinfo (2.0.6)
concurrent-ruby (~> 1.0)
unicode-display_width (1.8.0)
- uri (0.13.1)
+ uri (1.0.2)
webrick (1.9.0)
PLATFORMS
diff --git a/docs/_spec/openapi-split.yaml b/docs/_spec/openapi-split.yaml
index f1793beb..5f4159d1 100644
--- a/docs/_spec/openapi-split.yaml
+++ b/docs/_spec/openapi-split.yaml
@@ -6,41 +6,51 @@ info:
url: "images/TROLIE-horizontal-color.svg"
description: |
- Pursuant to FERC Order 881, Transmission Providers are required to support
- Ambient Adjusted Ratings (AARs) for most Transmission Facilities in their
- footprint. In this context, Transmission Providers refers roughly to the
- FERC definition of Transmission Provider as any public utility that owns,
- operates, or controls facilities used for the transmission of electric
- energy in interstate commerce. This could be said to apply to any entity
- that operates the transmission grid, including ISOs.
-
- For the purpose of this API, Transmission Provider may be assumed to be more
- generic- it is really any entity that can receive AARs. This API
- specification supports the information exchange necessary to coordinate
- forecasted and base facility ratings between a Transmission Provider and
- Ratings Providers. The Transmission Provider is assumed to be the host of
- this information exchange.
-
- A Ratings Provider is defined by this specification to be any entity that
- has pre-coordinated with the Transmission Provider hosting this information
- exchange to be the entity responsible for providing AARs on some set of
- Transmission Facilities known to the Transmission Provider. That
- pre-coordination is out-of-scope for this specification. The language of
- this API makes a strict distinction between the terms rating and limit.
-
- A limit is a validated value that is actively used to make operational
- decisions on the power grid. This could be limits used by the EMS or
- real-time market in real-time, or it could be forecast limits used by
- look-ahead processes such as EMS study applications or the day-ahead market.
-
- A rating, in contrast, is a calculated value from some process that is input
- to TROLIE (and by extension operating power systems at large) and may be
- selected for use as a limit after validation and dependent on operating
- conditions, time frame and the operational decisions being made. Seasonal
- ratings, forecast rating proposals, and real-time rating proposals are all
- examples of ratings.
-
- 
+ This specification defines a set of operations for the exchange of power
+ system ratings and limits between entities that own and operate the electric
+ power system in North America. In particular, it is designed to support the
+ exchange of Ambient Adjusted Ratings (AARs), pursuant to FERC Order 881. It
+ is published as a community standard to facilitate interoperability
+ in these exchanges.
+
+ The specification conceives of the exchange as being between two primary
+ entities:
+
+ * A [Ratings Provider](https://trolie.energy/concepts#ratings-provider) is
+ an entity that is responsible for providing ratings on some set of power
+ system resources, e.g., Transmission Facilities, typically a Transmission
+ Owner or Transmission Operator. The ratings are provided to a
+ Clearinghouse Provider whose is responsible for determining the operating
+ limits of the power system resources.
+
+ * The [Clearinghouse Provider](https://trolie.energy/concepts#clearinghouse-provider) is
+ typically a Transmission Provider (FERC) and a Reliability Coordinator (NERC).
+
+ Adjacent Clearinghouse Providers exchange ratings in order to establish
+ operating limit values for the power system resources that are shared
+ between them.
+
+ A Ratings Provider is assumed by this specification to have pre-coordinated
+ with a Clearinghouse Provider to identify the former's Ratings Obligation,
+ i.e., the set of power system resources for which they will provide ratings.
+ Additionally, the Ratings Provider will have similarly pre-coordinated the
+ definition of their Monitoring Sets, i.e., their power system limits of
+ interest. The nature and method of pre-coordination is out-of-scope for this
+ specification.
+
+ Note that this API makes a strict distinction between the terms rating and
+ limit. Colloquially, these terms are often used interchangeably. However,
+ in the context of this specification, they have distinct meanings. At a
+ high-level, the specification defines an exchange where ratings go in and
+ limits come out. A Clearinghouse is a function for determining the operating
+ limits from the ratings it has on-hand, including those that are proposed by
+ Ratings Providers and any applicable time-bound static ratings.
+
+ This interaction diagram highlights the primary requests and responses that
+ are defined in this spec. Note that not all of the operations will be
+ supported by every implementation.
+
+ 
version: 1.0.0-wip-realtime-stable
contact:
@@ -56,130 +66,112 @@ tags:
- name: Real-Time
description: |
+ If permitted by the Clearinghouse Provider, its Ratings Providers can use
+ these functions to exchange real-time ratings, supplementing or replacing
+ traditional telemetry protocols like ICCP.
- At the discretion of the TROLIE server owner, Ratings Providers may use
- these functions to exchange ratings within the current hour, either as an
- alternative or supplement to traditional telemetry protocols such as ICCP.
-
- These are assumed to be real-time ratings, based on measurements of
- ambient conditions as opposed to forecasts. These ratings will be used by
- Transmission Providers in real-time grid operations processes, such as
- state estimator and real-time markets. The clearinghouse for real-time
- ratings may be run more frequently than the one for forecast ratings to
- adapt to real-world conditions.
+ These ratings are based on real-time measurements of ambient conditions
+ and will be used by Transmission Providers for real-time grid operations
+ processes, including state estimation and real-time markets. The clearing
+ of real-time ratings may be more frequent than for forecast ratings, but
+ the frequency is the prerogative of the Clearinghouse Provider.
These ratings may be either AARs or DLRs.
- name: Forecasting
description: |
-
- The operations related to data exchange of forecasted ratings.
-
- This data exchange specifically includes the 240-hour-ahead forecasted AAR
- data exchange between Ratings Providers and Transmission Providers
- mandated FERC order 881. It includes the ability to submit rating
- proposals, query back in-use limits, and monitor the health and validity
- of the rating proposal submissions relative the Rating Provider's
- obligations.
+ The Forecasting API operations define the exchange of forecasted ratings,
+ including the 240-hour-ahead forecasted AAR data exchange required by FERC
+ Order 881. The operations support submitting rating proposals, querying
+ in-use limits, and monitoring the health and validity of submissions
+ against the Rating Provider's obligations.
- name: Seasonal
description: |
-
Seasonal ratings are static ratings associated with extended durations,
- typically months. These are used in both planning and operations.
-
- For Ratings Obligations with an AAR Exemption, the power system resource
- will be generally operated to a seasonal rating. For Ratings Obligations
- that *are* satisfied with dynamic ratings, a seasonal rating is still
- required, because the seasonal rating is typically used as a recourse
- rating when a dynamic rating is unavailable for any reason. For example, a
- dynamic rating would likely not be available during a communication outage
- or when determining a forecast rating for the power system resource beyond
- the period for which a forecast has been provided, e.g., beyond the ten
- day forecast required by FERC Order 881.
-
- A snapshot is provided of the resource ratings configured by the system,
- as well as their relationship to upcoming seasons.
+ typically months. These are typically used in both planning and
+ operations.
+
+ Power system resources that are exempt from providing AARs generally
+ operate at a seasonal rating. Even for resources using dynamic ratings, a
+ seasonal rating is still necessary. This acts as a recourse when a dynamic
+ rating is unavailable. For example, a dynamic rating
+ might be unavailable during communication outages or for forecasts beyond
+ the ten-day period required by FERC Order 881.
- name: Seasonal Overrides
description: |
+ A Seasonal Override instructs the system to use a temporary static rating
+ instead of any concurrent Seasonal Rating for a resource.
- A Seasonal Override is an instruction to use a temporary static rating set
- in lieu of any concurrent Seasonal Rating for a given resource.
-
- A typical use case is a so-called "de-rate" due to temporary clearance
+ A typical use case is a so-called 'de-rate' due to a temporary clearance
issue for a transmission facility that is exempt from providing AARs.
- Exempt facilities normally operate against a seasonal rating, yet rather
- than provide a seasonal ratings schedule update, the Ratings Provider
- could send a Seasonal Override. During the provided duration of the
- override, the Transmission Provider would operate to the Seasonal Override
- rather than any ratings that would have been used from the seasonal rating
- schedule.
-
- In contrast, for a resource that is *not* exempt from providing AARs, the
- Ratings Provider would issue a Temporary AAR Exception to the
- Clearinghouse Provider to address a clearance issue or other temporary
- operating condition that calls for a static rating.
+
+ Exempt facilities typically operate at a seasonal rating. However, instead
+ of updating the seasonal rating schedule, a Ratings Provider can send a
+ Seasonal Override.
+
+ During the override period, the Clearinghouse uses the Seasonal
+ Override rating instead of any scheduled seasonal ratings.
+
+ For resources required to provide AARs, a Ratings Provider would issue a
+ Temporary AAR Exception to address temporary conditions requiring a static
+ rating.
- name: Temporary AAR Exceptions
- description: >
-
- A Temporary AAR Exception is an exception to the AAR process, due to some
- unusual condition on the facility. This could occur in various
- scenarios:
-
- * An equipment failure.
-
- * An unforeseen condition on a related part of the power grid.
-
- * Some ambient condition that is not part of the model is heating the
- line.
-
- * Something in the surrounding environment is effecting the amount that a
- line is allowed to sag. For example, this may occur for lines over rivers
- when very large ships pass under them.
-
- The purpose and behavior of a temporary rating is two-fold.
-
- First, according to FERC, all exceptions to normal rating must be
- documented and kept with history. The actual numbers for the forecasted
- and real-time feeds may still continue through proposals submitted to
- TROLIE. However, the presence of a temporary rating, and the reason that
- it occurred, must be captured in history regardless of the actual numbers.
- The Temporary AAR Exception may be held simply for that record-keeping
- purpose. It must also include a specific rating used during the incident,
- which is typically a recourse rating. The reason and the end
- date of the effective window may be updated after the object has been
- created, up to a configurable threshold.
-
- If the targeted resource is getting AAR data feeds, then it _may_ be assumed
- that those AAR data feeds from the Ratings Provider will simply reflect the
- temporary condition. The ClearingHouse Provider then may decide whether to use
- the raw AAR data feeds or the ratings from the temporary AAR exception.
-
- However, this doesn't always apply, leading to the
- second usage. Actual rating values must in Temporary AAR Exceptions
- must be used when we cannot expect AAR feeds otherwise. This
- occurs in two scenarios:
-
- 1. It is required when the Transmission Provider is generating forecast
- rating proposals, from lookup tables for example. There is no external
- AAR data feed, and the Transmission Provider wouldn't otherwise know how
- to forecast the ratings given this temporary condition. For these
- scenarios, a complete rating value set MUST be provided.
-
- 2. For facilities where AAR data is provided, it is possible that the AAR
- data feed could be down for some reason. Therefore, this provides a
- placeholder set of numbers until the AAR data feed is repaired.
+ description: |
+ A [Temporary AAR Exception](https://trolie.energy/concepts#temporary-aar-exception) is
+ provided by the Ratings Provider when a Ratings Obligation cannot be
+ fulfilled, due to some temporary operating condition impacting the related
+ power system resource. This could occur in various scenarios:
+
+ * An equipment failure.
+ * An unforeseen condition on a related part of the power grid.
+ * Some ambient condition that is not part of the model is heating the
+ line, like a wildfire.
+ * Something in the surrounding environment is affecting the amount that a
+ line is allowed to sag. For example, this may occur for lines over
+ rivers when very large ships pass under them
+
+ A Temporary AAR Exception serves two main purposes: documenting the reason
+ for the exception and providing a temporary rating value set. It is employed
+ in three distinct circumstances:
+
+ 1. Firstly, Order 881 mandates documentation and archival of all use of
+ alternate ratings in lieu of AARs. Ratings Providers should continue to
+ provide real-time and forecast ratings for the affected resource, but
+ these should match the rating provided with the Temporary AAR Exception
+ while the latter is in effect. This temporary rating, and the reason that
+ it occurred, must be captured in history regardless of the provided
+ ratings. The reason and the end date of the effective window may be
+ updated after the object has been created, up to a configurable threshold.
+
+ If the Ratings Providers provides ratings that deviate from the static
+ Temporary AAR Exception rating, the Clearinghouse Provider must decide
+ whether to use those or the static rating. The Clearinghouse Provider
+ advise its Ratings Providers on how it will choose ahead of time. This
+ specification recommends using the dynamic rating provided, but it does
+ not mandate it.
+
+ 2. Secondly, Temporary AAR Exceptions apply when the Clearinghouse
+ Provider is generating forecast rating proposals on behalf of the Ratings Provider, e.g., when lookup tables are provided ahead of time by the Ratings Provider.
+ Since there is no external ratings, the Clearinghouse Provider
+ wouldn't otherwise know that a temporary static rating is needed.
+
+ 3. Finally, for facilities where dynamic ratings are provided, it is
+ possible that a communications outage or other issue could prevent the
+ Clearinghouse Provider from receiving the dynamic ratings. In this case,
+ the Clearinghouse Provider would use a Temporary AAR Exception rating.
- name: Monitoring Sets
- description: >
-
- Monitoring Sets are named sets of power system resources that may be used to
- filter ratings and limits returned by queries against these APIs. How Monitoring
- Sets are defined is beyond the scope of the TROLIE specification, and it is
- assumed that the sender and receiver have predefined the appropriate Monitoring
- Sets. More on monitoring sets may be found at https://trolie.energy/concepts.html#monitoring-sets
+ description: |
+
+ [Monitoring Sets](https://trolie.energy/concepts#monitoring-sets) are
+ named sets of power system resources that may be used to filter ratings
+ and limits returned by queries against these APIs. How Monitoring Sets are
+ defined is beyond the scope of the TROLIE specification, and it is assumed
+ that the sender and receiver have predefined the appropriate Monitoring
+ Sets.
- name: limit-type
description:
diff --git a/docs/_spec/paths/limits_forecast-snapshot.yaml b/docs/_spec/paths/limits_forecast-snapshot.yaml
index 9e77d392..81a057ce 100644
--- a/docs/_spec/paths/limits_forecast-snapshot.yaml
+++ b/docs/_spec/paths/limits_forecast-snapshot.yaml
@@ -12,44 +12,54 @@ current:
- $ref: ../components/parameters/static-only.yaml
description: |
- Obtain the Limits Forecast the Transmission Provider is currently using in
- Operations, relative to the current time.
-
- This operation uses media types to control verbosity of the data
- fetched. The default media type,
- `application/vnd.trolie.forecast-limits-snapshot.v1+json`, simply includes
- the rating data. For applications that need it, the media type
- `application/vnd.trolie.forecast-limits-detailed-snapshot.v1+json` may be
- requested, which also references the source proposals used to generate the
- snapshot, as well as reporting data from the ratings clearing process.
-
- The `application/vnd.trolie.forecast-limits-snapshot.v1+json` and
- `application/vnd.trolie.forecast-limits-detailed-snapshot.v1+json` media
- types support the `include-psr-header` parameter. This is a boolean
- parameter that defaults to `true`. When set to `false`, the
+ Returns the latest Limits Forecast the clearinghouse has produced.
+
+ This content of the response varies significantly based on the media type requested.
+
+ * `application/vnd.trolie.forecast-limits-snapshot.v1+json` simply includes the limits.
+ * For use cases that require understanding *how* the limits were determined,
+ the media type `application/vnd.trolie.forecast-limits-detailed-snapshot.v1+json`
+ is available; it contains the ratings proposals and other factors used to
+ generate the limits.
+
+ Both of these media types support the `include-psr-header` parameter. This
+ is a boolean parameter that defaults to `true`. When set to `false`, the
`power-system-resource` header is omitted. This can result in smaller
payloads when the client already knows the resource ids in use by the
Clearinghouse Provider.
+
```http
GET /limits/forecast-snapshot HTTP/1.1
Accept: application/vnd.trolie.forecast-limits-detailed-snapshot.v1+json; include-psr-header=false
```
- Additionally, the `application/vnd.trolie.forecast-limits-snapshot-slim.v1+json`
- media type may be used to request a more concise representation of the data.
- The media type parameter `limit-type` is required to specify the type of limit
- being requested. For example,
+ ### Slim Format
+
+ The `application/vnd.trolie.forecast-limits-snapshot-slim.v1+json` media type
+ may be used to request a more concise representation of the data. The
+ media type parameter `limit-type` is required to specify the type of limit
+ being requested, for example:
+
```http
GET /limits/forecast-snapshot HTTP/1.1
Accept: application/vnd.trolie.forecast-limits-snapshot-slim.v1+json; limit-type=apparent-power
```
- Note this format is much more concise but requires significant care in processing.
- See [Using Slim Media Types](../example-narratives/using-slim-media-types) for more details.
+ Additionally, the `inputs-used` parameter may be set to `true` to include
+ the inputs used to generate the forecast.
+ ```http
+ GET /limits/forecast-snapshot HTTP/1.1
+ Accept: application/vnd.trolie.forecast-limits-snapshot-slim.v1+json; limit-type=apparent-power; inputs-used=true
+ ```
+
+ Note this format is much more concise but requires significant care in
+ processing. See [Using Slim Media
+ Types](../example-narratives/using-slim-media-types) for more details.
Clients SHOULD perform Conditional `GET` using the `If-None-Match` header
and the `ETag` of a previous `GET` response to poll this endpoint. Rate
limiting is done on a per Ratings Provider basis, so requests from
- independent clients used by the same provider count against the same quota.
+ independent clients used by the same provider count against the same
+ quota.
responses: &responses
'200':
diff --git a/docs/_spec/paths/rating-proposals_realtime.yaml b/docs/_spec/paths/rating-proposals_realtime.yaml
index 4724a9e8..20aca9c4 100644
--- a/docs/_spec/paths/rating-proposals_realtime.yaml
+++ b/docs/_spec/paths/rating-proposals_realtime.yaml
@@ -1,26 +1,23 @@
get:
operationId: getRealTimeProposalStatus
- summary: Obtain the status of the Ratings Provider's Real-Time proposals
+ summary: Real-Time Proposals Status
description: |
- Used to obtain the status of real-time ratings proposals. The response is
- implicitly restricted to the requesting Ratings Provider's obligation.
- Accordingly, the caller can use this endpoint to check the state of their
- proposal submission.
-
- Note that the same status object is returned for each
- `postRealTimeProposal`, so this endpoint may seem redundant. However,
- an anticipated use case for this `GET` endpoint is to support supervisor
- processes that are setup by the client to independently ensure the provider's process for
- rating submission if functioning properly. For example, the Rating Provider
- might have one program responsible for producing and submitting Ratings
- via `postRealTimeProposal`, while having a separate
- monitoring job that checks this endpoint regularly.
-
- Clients SHOULD perform Conditional `GET` using the `If-None-Match` header
- and the `ETag` of a previous `GET` response to poll this endpoint. Rate
- limiting is done on a per Ratings Provider basis, so requests from
- independent clients used by the same provider count against the same quota.
+ Retrieves the status of a real-time ratings proposal. The response is
+ limited to the requestor's current proposal.
+
+ Note this status resource is also returned for each `postRealTimeProposal`
+ call. The anticipated use case for this endpoint is to monitoring proposal
+ submissions: Clients can use this operation to independently verify that
+ their proposal submission process is functioning correctly. This is
+ particularly useful for scenarios where a separate monitoring job is set up
+ to check the status of proposals.
+
+ Rate limiting is applied per Ratings Provider, meaning requests from
+ multiple clients associated with the same provider count towards the same
+ quota. To optimize network traffic and server load, clients should perform
+ conditional GET requests with the `If-None-Match` header and the `ETag` from
+ a previous response.
tags: &tags
- Real-Time
@@ -59,45 +56,43 @@ post:
summary: Submit Real-Time Rating Proposal
description: |
- At the discretion of the TROLIE server owner, Ratings Providers use
- this endpoint to submit ratings within the current hour.
- These are assumed to be real-time ratings, based on measurements
- of ambient conditions as opposed to forecasts. These ratings will be
- used by Transmission Providers in real-time grid operations processes,
- such as state estimator and real-time markets. The clearinghouse for real-time ratings
- may be run more frequently than the one for forecast ratings to adapt to real-world
- conditions.
-
- These ratings may be either AARs or DLRs.
-
- The API mechanics are different than forecasts, as there is no implicitly created
- time window to modify. Ratings providers simply `POST` new values as they are measured and computed.
-
- Rules for usage however are similar to forecasts; real-time proposals do not have to contain
- every resource for which the Ratings Provider is responsible. Data may be broken into batches
- across the Rating Provider's footprint.
-
- Status of the real-time proposals also includes an indication of incomplete obligations, much
- like forecast. However, the meaning of this is somewhat different, as it simply indicates
- data that is either completely missing, or is considered stale by the Clearinghouse Provider,
- likely due to simply not receiving a value within a reasonable period, such as an hour.
-
- There are two supported media types for a Real-Time Ratings proposals.
-
- `application/vnd.trolie.rating-realtime-proposal.v1+json` allows the
- Ratings Provider to combine different limit types, such as
- `apparent-power` (MVA) and `current` (MW), in a single proposal.
-
- `application/vnd.trolie.rating-realtime-proposal-slim.v1+json` for
- proposals that only require a single limit type, e.g., `apparent-power`.
- Clients *MUST* specify that [limit-type](#tag/limit-type) as a media type
- parameter. For example,
- ```http
- POST /ratings-proposals/realtime HTTP/1.1
- Content-Type: application/vnd.trolie.rating-realtime-proposal-slim.v1+json; limit-type=apparent-power
- ```
- Note that this format is much more concise but requires significant care
- in serialization/deserialization. For details, see [Using Slim Media Types](../example-narratives/using-slim-media-types).
+ Some Clearinghouse Providers will support real-time ratings submissions
+ through this operation.
+
+ The API mechanics are different than forecasts, as there is no implicitly
+ created time window to modify. Ratings providers simply `POST` new values
+ as they are measured and/or computed.
+
+ Rules for usage however are similar to forecasts; real-time proposals do not
+ have to contain every resource for which the Ratings Provider is
+ responsible. Data may be broken into batches across the Rating Provider's
+ footprint.
+
+ Status of the real-time proposals also includes an indication of incomplete
+ obligations, much like forecast. However, the meaning of this is somewhat
+ different, as it simply indicates data that is either completely missing, or
+ is considered stale by the Clearinghouse Provider, likely due to simply not
+ receiving a value within a reasonable period, such as an hour.
+
+ There are two supported media types for Real-Time Ratings proposals.
+
+ * `application/vnd.trolie.rating-realtime-proposal.v1+json` allows the Ratings
+ Provider to combine different limit types, such as `apparent-power` (MVA)
+ and `current` (MW), in a single proposal.
+
+ * `application/vnd.trolie.rating-realtime-proposal-slim.v1+json` for
+ proposals that only require a single limit type, e.g., `apparent-power`.
+ Clients *MUST* specify that [limit-type](#tag/limit-type) as a media type
+ parameter. For example,
+
+ ```http
+ POST /ratings-proposals/realtime HTTP/1.1
+ Content-Type: application/vnd.trolie.rating-realtime-proposal-slim.v1+json; limit-type=apparent-power
+ ```
+
+ Note that this format is much more concise but requires significant care
+ in serialization/deserialization. For details, see [Using Slim Media
+ Types](../example-narratives/using-slim-media-types).
tags: *tags
@@ -121,9 +116,15 @@ post:
'202':
description: |
- Accepted. The update was accepted for later processing by the Clearinghouse.
- Updates to ratings may need to undergo additional validation and
- propagation to other systems.
+ Accepted. The update was accepted for later processing by the
+ Clearinghouse. Updates to ratings may need to undergo additional
+ validation and propagation to other systems.
+
+ Be sure to check the `incomplete-obligation-count` value is zero; if it
+ is non-zero, the Clearinghouse Provider does not have a valid and
+ non-stale real-time rating for one or more Ratings Obligations.
+ Providers should impute recourse ratings as necessary to ensure their
+ proposals are complete, i.e., the entire Ratings Obligation is met.
content:
application/vnd.trolie.rating-realtime-proposal-status.v1+json:
@@ -147,25 +148,17 @@ post:
Unprocessable Content. The Real-Time Ratings Proposal may
not utilize units that are not permitted by the
- Clearinghouse Provider. Check the response for details. Ratings
- Providers should impute recourse ratings as necessary to ensure their
- proposals are complete, i.e., the entire Ratings Obligation is met.
+ Clearinghouse Provider. Check the response for details.
content:
application/problem+json:
schema:
$ref: '../openapi-split.yaml#/components/schemas/problem'
- # ideally this would be examples (plural) and include both invalid units and incomplete proposal
- # but `redocly bundle` extracts examples as standalone components/examples in the consolidated spec
- # and unfortunately `redocly lint` then gives validation errors on those examples
- #
- #examples:
- # invalid-units:
- # $ref: '../../articles/examples/proposal-invalid-units.json'
- # incomplete-proposal:
- # $ref: '../../articles/examples/incomplete-proposal.json'
- example:
- $ref: '../../articles/examples/incomplete-proposal.json'
+ examples:
+ invalid-units:
+ summary: Invalid Units Provided in Real-Time Proposal
+ value:
+ $ref: '../../articles/examples/proposal-invalid-units.json'
headers:
$ref: '../openapi-split.yaml#/components/responses/304/headers'
'429': *rate-limit-hit
diff --git a/docs/articles/examples/incomplete-proposal.json b/docs/articles/examples/incomplete-proposal.json
deleted file mode 100644
index 265bb765..00000000
--- a/docs/articles/examples/incomplete-proposal.json
+++ /dev/null
@@ -1,6 +0,0 @@
-{
- "type": "//trolie.example.com/spec/client-errors/422/incomplete-proposal",
- "title": "Unprocessable Entity: Incomplete proposal",
- "status": 422,
- "detail": "The proposal is incomplete, so unprocessable. Missing from the Ratings Obligation are: 8badf00d."
-}
diff --git a/docs/images/TROLIE Ratings Provider interactions.excalidraw.png b/docs/images/TROLIE Ratings Provider interactions.excalidraw.png
deleted file mode 100644
index d4a471a0..00000000
Binary files a/docs/images/TROLIE Ratings Provider interactions.excalidraw.png and /dev/null differ
diff --git a/docs/images/interactions.excalidraw.png b/docs/images/interactions.excalidraw.png
new file mode 100644
index 00000000..b3e2daa8
Binary files /dev/null and b/docs/images/interactions.excalidraw.png differ