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:

  1. The limit-type used in the proposal is specified by the Ratings Provider as a parameter of the media type. The limit-type chosen determines the layout of the ratings values.
  2. The ratings are provided in order of decreasing duration, e.g., continuous then emergency then load shed.
  3. The facilities are required to be in the same order they appear in the header.
  4. The seasons are required to be in the same order they appear in the header.
  5. 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 the Content-Type header (line 2 above) is 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 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-1.0#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
      ]
    ]
  ]
}