The “slim” media types provided by TROLIE include:
application/vnd.trolie.rating-realtime-proposal-slim.v1+json
application/vnd.trolie.seasonal-ratings-proposal-slim.v1+json
application/vnd.trolie.rating-forecast-proposal-slim.v1+json
application/vnd.trolie.forecast-limits-snapshot-slim.v1+json
application/vnd.trolie.realtime-limits-snapshot-slim.v1+json
These slim snapshots and proposals require the limit-type
media type parameter
to be specified. The following names are valid values for the limit-type
parameter.
active-power
active-power-with-power-factor
apparent-power
current
current-with-kV
reactive-power
overvoltage-threshold-pu
overvoltage-threshold
undervoltage-threshold-pu
undervoltage-threshold
These correspond to the valid Limit Types.
Here’s an example that requests a slim forecast limits snapshot
1
2
GET /limits/forecast-snapshot HTTP/1.1
Accept: application/vnd.trolie.forecast-limits-snapshot-slim.v1+json; limit-type=apparent-power
This “slim” format is much more space-efficient but requires a few processing steps and assumptions:
- The
limit-type
used in the proposal is specified by the Ratings Provider as a parameter of the media type. Thelimit-type
chosen determines the layout of the ratings values. - The ratings are provided in order of decreasing duration, e.g., continuous then emergency then load shed.
- The facilities are required to be in the same order they appear in the header.
- The seasons are required to be in the same order they appear in the header.
- Each forecast must have the number of hourly forecasts corresponding to the 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. 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.
curl
Example
1
2
3
4
5
curl -X PATCH \
-H "Content-Type: application/vnd.trolie.seasonal-ratings-proposal-slim.v1+json; limit-type=apparent-power" \
-H "Accept: application/vnd.trolie.seasonal-ratings-proposal-status.v1+json, */*" \
-d @seasonal-ratings.json \
$TROLIE_SERVER_URL/ratings-proposals/seasonal
The
limit-type
parameter in theContent-Type
header (line 2 above) is required by the TROLIE specification for theapplication/vnd.trolie.seasonal-ratings-proposal-slim.v1+json
media type, as no defaultlimit-type
can be assumed. See Limit Types for the other options defined in the spec.
The
Accept
header in this example specifies one of the Status Responses.
HTTP Headers
The previous curl
request would result in an HTTP request like the following:
1
2
3
4
PATCH /ratings-proposals/seasonal HTTP/1.1
Host: trolie.example.com
Accept: application/vnd.trolie.seasonal-ratings-proposal-status.v1+json, */*
Content-Type: application/vnd.trolie.seasonal-ratings-proposal-slim.v1+json; limit-type=apparent-power
Payload
For illustrative purposes here, we present the JSON payload with inline comments. However, comments are not permitted in the TROLIE media types.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
{
"proposal-header": {
"source": { /* ...details elided for clarity... */ },
"default-emergency-durations": [
{ "name": "emergency", "duration-minutes": 240 },
{ "name": "load shed", "duration-minutes": 15 }
],
"power-system-resources": [
{ "resource-id": "8badf00d",
"alternate-identifiers": [ { "name": "segmentX", "authority": "TO-NERC-ID" } ]
}, {
"resource-id": "f34d3d",
"alternate-identifiers": [ { "name": "segmentY", "authority": "TO-NERC-ID" } ]
}
],
"default-seasonal-schedule": {
"schedule": [
{ "season-name": "WINTER", "begins": "2024-11-15T00:00:00-05:00" },
{ "season-name": "SPRING", "begins": "2025-03-01T00:00:00-05:00" },
{ "season-name": "SUMMER", "begins": "2025-06-15T00:00:00-05:00" },
{ "season-name": "FALL", "begins": "2025-09-01T00:00:00-05:00" }
],
"ends": "2025-11-15T00:00:00-05:00"
}
},
"ratings": [
// 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
[ // resource-id: 8badf00d
[ // season-name: WINTER
160, //continuous MVA
170, //emergency MVA
200, //load shed MVA
],
[ // season-name: SPRING
155, //continuous MVA
160, //emergency MVA
200 //load shed MVA
],
[ // season-name: SUMMER
145, //continuous MVA
150, //emergency MVA
200 //load shed MVA
],
[ // season-name: FALL
155, //continuous MVA
160, //emergency MVA
200 //load shed MVA
]
],
[ // resource-id: f34d3d
[ // season-name: WINTER
161, //continuous MVA
171, //emergency MVA
201 //load shed MVA
],
[ // season-name: SPRING
156, //continuous MVA
161, //emergency MVA
201 //load shed MVA
],
[ // season-name: SUMMER
146, //continuous MVA
151, //emergency MVA
201 //load shed MVA
],
[ // season-name: FALL
156, //continuous MVA
161, //emergency MVA
201 //load shed MVA
]
]
]
}