Update schemas and examples for Framework 5.1.0

.circleci/config.yml

@@ -8,7 +8,7 @@
        - run: sudo apt-get install openjdk-8-jre-headless
        - run: openapi-generator version
        - checkout
-       - run: for i in `find -name "*.yaml"`; do openapi-generator validate -i $i; done
+       - run: find endpoints -name \*.yaml -a ! -name _\*.yaml | xargs -0 -n1 -P1 openapi-generator validate -i
  workflows:
    version: 2
    validation:

endpoints/api.yaml

@@ -1,14 +1,6 @@
 openapi: "3.0.0"
-components:
-  securitySchemes:
-    bearerAuth:
-      type: http
-      scheme: bearer
-      bearerFormat: JWT
-security:
-  - bearerAuth: []
 info:
-  version: 5.0.0
+  version: 5.1.0
   title: Trading Interface Automation Framework For Local TV Transactions.
   description: |
     # Television Interface Practices Initiative (TIP)
@@ -30,6 +22,7 @@ info:
 
     | Version | Date | Description | Author |
     |---------|------|-------------|--------|
+    | Release 5.1.0 | August 13, 2020 | Release 5.1.0 | Frontrow Advisory |
     | Release 5.0.0 | May 5, 2020 | Release 5.0.0 | Frontrow Advisory |
     | Release 4.0 | May 16, 2019 | Release 4.0 (WORKING DRAFT) | Frontrow Advisory |
     | Release 3.1 | February 1, 2019 | Release 3.1 | Frontrow Advisory |
@@ -41,6 +34,39 @@ info:
     | Draft | October 9, 2017 | Revised Draft | Frontrow Advisory |
     | Draft | September 25, 2017 | Initial Draft | Frontrow Advisory |
 
+    ## Release 5.1.0 Notes
+
+    | Changes from Release 5.0.0 to Release 5.1.0 |
+    |---------------------------------------------|
+    | Added Transaction Type guidelines to framework |
+    | Added new section to each tab to indicate the valid methods |
+    | Added new common object to support budgetAllocations by budget type |
+    | Added new common object to support budget amount and optional budgetAllocation common object |
+    | Changed the budget property in RFP from Property to Object |
+    | Added new budget common object to Proposal and Order |
+    | Added new BuyerProposals to framework to support buyer change requests to a seller's proposal |
+    | Changed SellerMakegoodOffers to support an array of preemptDetails and makegoodOfferDetails with the option to link preempt details to makegood offer or makegood offer(s) to preempt detail e.g. 1:1, 2:1, etc. |
+    | Added external comments to the SalesElementTransactionInventory and SalesElementTransactionDate that may be used for overall comments and/or the change request rationale to a proposal or order |
+    | Changed dealYear property in Proposal and Order from Integer to String |
+    | Added new section to each tab to indicate the valid response codes |
+    | Added mediaoutlet object to BuyerMakegoodGuidelines |
+    | Added SellerImpressions (Video/OTT) |
+    | Added new common objects to framework to support SellerImpressions |
+    | Added JSON examples to Github |
+    | Renamed several endpoint names to plural (Avails, RFPs, Proposals, Orders, Invoices) to follow OpenAPI naming conventions |
+    | Added salesOffice to Contact common object |
+    | Added SellerCommercialInstructions to the framework to support confirm or reject of commercial instructions |
+    | BuyerOrderRecall - Now included in BuyerOrder |
+    | SellerOrderConfirm - Now included in SellerOrder (NEW) |
+    | SellerOrderReject - Now included in SellerOrder (NEW) |
+    | SellerMakegoodRecall - Now included in SellerMakegoodOffer |
+    | BuyerMakegoodConfirm - Now included in BuyerMakegoodOffer (NEW) |
+    | BuyerMakegoodReject - Now included in BuyerMakegoodOffer (NEW) |
+    | Changed ratingSource and ratingStream in the AudienceSegment common object from enums to strings |
+    | Added type to the audiencePricingMetric common object that identifies the type of audience and /or pricing being provided (Selling, Actual or Projection) |
+    | Added Report Window to Impressions |
+    | Added new examples section |
+
     ## Release 5.0.0 Notes
 
     | Changes from Release 4.2.0 to Release 5.0.0 | Source |
@@ -128,36 +154,48 @@ info:
     url: https://opensource.org/licenses/MIT
 servers:
   - url: http://placeholderdomain.io
+security:
+  - bearerAuth: []
 paths:
-  /buyer/commercialInstructions:
-    $ref: 'commercialInstructions.yaml#/paths/~1buyer~1commercialInstructions'
   /buyer/inventoryAvails:
     $ref: 'inventoryAvails.yaml#/paths/~1buyer~1inventoryAvails'
-  /buyer/inventoryAvails/cancel:
-    $ref: 'inventoryAvails.yaml#/paths/~1buyer~1inventoryAvails~1cancel'
-  /buyer/order:
-    $ref: 'orders.yaml#/paths/~1buyer~1order'
-  /buyer/order/cancel:
-    $ref: 'orders.yaml#/paths/~1buyer~1order~1cancel'
-  /buyer/rfp:
-    $ref: 'rfps.yaml#/paths/~1buyer~1rfp'
-  /buyer/rfp/cancel:
-    $ref: 'rfps.yaml#/paths/~1buyer~1rfp~1cancel'
-  /seller/logtimes:
-    $ref: 'logTimes.yaml#/paths/~1seller~1logtimes'
-  /seller/invoice:
-    $ref: 'invoice.yaml#/paths/~1seller~1invoice'
-  /seller/invoice/cancel:
-    $ref: 'invoice.yaml#/paths/~1seller~1invoice~1cancel'
   /seller/inventoryAvails:
     $ref: 'inventoryAvails.yaml#/paths/~1seller~1inventoryAvails'
-  /seller/inventoryAvails/cancel:
-    $ref: 'inventoryAvails.yaml#/paths/~1seller~1inventoryAvails~1cancel'
-  /seller/order/confirmation:
-    $ref: 'orders.yaml#/paths/~1seller~1order~1confirmation'
-  /seller/order/reject:
-    $ref: 'orders.yaml#/paths/~1seller~1order~1reject'
-  /seller/proposal:
-    $ref: 'proposal.yaml#/paths/~1seller~1proposal'
-  /seller/proposal/cancel:
-    $ref: 'proposal.yaml#/paths/~1seller~1proposal~1cancel'
+  /buyer/rfps:
+    $ref: 'rfps.yaml#/paths/~1buyer~1rfps'
+  /seller/proposals:
+    $ref: 'proposal.yaml#/paths/~1seller~1proposals'
+  /buyer/proposals:
+    $ref: 'proposal.yaml#/paths/~1buyer~1proposals'
+  /buyer/orders:
+    $ref: 'orders.yaml#/paths/~1buyer~1orders'
+  /seller/orders:
+    $ref: 'orders.yaml#/paths/~1seller~1orders'
+  /buyer/commercialInstructions:
+    $ref: 'commercialInstructions.yaml#/paths/~1buyer~1commercialInstructions'
+  /seller/commercialInstructions:
+    $ref: 'commercialInstructions.yaml#/paths/~1seller~1commercialInstructions'
+  /seller/makegood/guidelines:
+    $ref: 'makegoods.yaml#/paths/~1seller~1makegood~1guidelines'
+  /buyer/makegood/guidelines:
+    $ref: 'makegoods.yaml#/paths/~1buyer~1makegood~1guidelines'
+  /seller/makegood/offers:
+    $ref: 'makegoods.yaml#/paths/~1seller~1makegood~1offers'
+  /buyer/makegood/offers:
+    $ref: 'makegoods.yaml#/paths/~1buyer~1makegood~1offers'
+  /seller/impressions:
+    $ref: 'impressions.yaml#/paths/~1seller~1impressions'
+  /seller/logtimes:
+    $ref: 'logTimes.yaml#/paths/~1seller~1logtimes'
+  /seller/invoices:
+    $ref: 'invoice.yaml#/paths/~1seller~1invoices'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+    schemas:
+      $ref: './schemas/_index.yaml'
+    responses:
+      $ref: './schemas/_responses.yaml'

endpoints/commercialInstructions.yaml

@@ -1,14 +1,8 @@
 openapi: "3.0.0"
-components:
-  securitySchemes:
-    bearerAuth:
-      type: http
-      scheme: bearer
-      bearerFormat: JWT
 security:
   - bearerAuth: []
 info:
-  version: 5.0.0
+  version: 5.1.0
   title: Commercial Instructions
   description: >-
     Allows the creative agency or service provider of commercial instructions to send new or
@@ -23,31 +17,104 @@ info:
     name: MIT
     url: https://opensource.org/licenses/MIT
 servers:
-  - url: http://placeholderdomain.io
+  - url: http://placeholderdomain.io/v5.x.x
 paths:
   /buyer/commercialInstructions:
     post:
       tags:
         - Buyer
-      summary: Buyer Commercial Instructions POST
+      summary: Buyer or Creative Agencies to provide New, Change, Cancel or Recall Commercial Instructions
       description: >-
         Allows the creative agency or service provider of commercial instructions to send new or
         revised traffic instructions on how commercial copy should be applied to units (No request
-        from Seller is required)
-      operationId: commercialInstructionsPost
+        from Seller is required)<br/>
+        Supported Transaction Types: New, Change, Cancel, Recall
+      operationId: BuyerCommercialInstructions
       requestBody:
-        description: commercial instructions required
+        description: commercial instructions request body is required.
         required: true
         content:
           application/json:
             schema:
-              $ref: 'schemas/commercialInstructionSchemas.yaml#/components/schemas/CommercialInstructionsRequestObject'
+              $ref: '#/components/schemas/BuyerCommercialInstructions'
+            examples:
+              New:
+                value:
+                  $ref: 'examples/CommercialInstructionsNew.json'
+              Change:
+                value:
+                  $ref: 'examples/CommercialInstructionsChange.json'
+              Cancel:
+                value:
+                  $ref: 'examples/GenericCancel.json'
+              Recall:
+                value:
+                  $ref: 'examples/GenericRecall.json'
       responses:
-        '200':
-          description: request accepted successfully
-        default:
-          description: unexpected error
-          content:
-            application/json:
-              schema:
-                $ref: 'schemas/commonSchemas.yaml#/components/schemas/Error'
+        '200': #OK
+          $ref: 'schemas/commonResponses.yaml#/components/responses/Success'
+        '400': #Bad Request
+          $ref: 'schemas/commonResponses.yaml#/components/responses/BadRequest'
+        '401': #Unauthorized
+          $ref: 'schemas/commonResponses.yaml#/components/responses/Unauthorized'
+        '403': #Forbidden
+          $ref: 'schemas/commonResponses.yaml#/components/responses/Forbidden'
+        '404': #Not Found
+          $ref: 'schemas/commonResponses.yaml#/components/responses/NotFound'
+        '405': #Not Allowed
+          $ref: 'schemas/commonResponses.yaml#/components/responses/NotAllowed'
+        default: #unexpected
+          $ref: 'schemas/commonResponses.yaml#/components/responses/Unexpected'
+  /seller/commercialInstructions:
+    post:
+      tags:
+        - Seller
+      summary: Seller optionally confirms or reject Commercial Instructions
+      description: >-
+        Allows the seller to respond to a new commercial instructions or comercial instructions changes with a confirm or reject.
+        Supported Transaction Types: Reject, Confirm
+      operationId: SellerCommercialInstructions
+      requestBody:
+        description: Request body is required to Confirm or reject Commercial Instructions
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: './schemas/commonSchemas.yaml#/components/schemas/CancelConfirmRecallReject'
+            examples:
+              Reject:
+                value:
+                  $ref: 'examples/GenericReject.json'
+              Confirm:
+                value:
+                  $ref: 'examples/GenericConfirm.json'
+      responses:
+        '200': #OK
+          $ref: 'schemas/commonResponses.yaml#/components/responses/Success'
+        '400': #Bad Request
+          $ref: 'schemas/commonResponses.yaml#/components/responses/BadRequest'
+        '401': #Unauthorized
+          $ref: 'schemas/commonResponses.yaml#/components/responses/Unauthorized'
+        '403': #Forbidden
+          $ref: 'schemas/commonResponses.yaml#/components/responses/Forbidden'
+        '404': #Not Found
+          $ref: 'schemas/commonResponses.yaml#/components/responses/NotFound'
+        '405': #Not Allowed
+          $ref: 'schemas/commonResponses.yaml#/components/responses/NotAllowed'
+        default: #unexpected
+          $ref: 'schemas/commonResponses.yaml#/components/responses/Unexpected'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+  schemas:
+    BuyerCommercialInstructions:
+      description: |
+        Users of this contruct have the option to either
+        <li>Use the full Commercial Instructions object to deliver New, or change instructions
+        <li>Use the alternate object to recall, or cancel a previously sent instructions.
+      oneOf:
+        - $ref: './schemas/commercialInstructionSchemas.yaml#/components/schemas/BuyerCommercialInstructions'
+        - $ref: './schemas/commonSchemas.yaml#/components/schemas/CancelConfirmRecallReject'

endpoints/examples/BuyerInventoryAvailsNew.json

@@ -0,0 +1,102 @@
+{
+    "transactionHeader": {
+      "tipVersion": "5.0.0",
+      "transactionId": {
+        "transactionId": "77DABA23-BC53-4E78-BCDE-AF527F1E62D6",
+        "transactionType": "New",
+        "sourceId": "WPP",
+        "sourceName": "WPP Group"
+      },
+      "timeStamp": "2020-06-09T22:40:17.432Z"
+    },
+    "dateSubmitted": "2020-06-09",
+    "dueDate": "2020-06-09",
+    "mediaOutlets": [
+      {
+        "mediaOutletId": "427CAD68-2375-44E6-8A25-F13557FD01F8",
+        "mediaOutletName": "WXYZ News Live",
+        "mediaOutletType": "Broadcast TV",
+        "mediaOutletChannel": "58.1",
+        "mediaOutletMarketName": "South Eastern Wisconsin",
+        "mediaOutletReference": "string"
+      }
+    ],
+    "buyer": {
+      "buyerId": "string",
+      "buyerName": "string",
+      "buyerReference": "string"
+    },
+    "advertiser": {
+      "advertiserId": "string",
+      "advertiserName": "string",
+      "advertiserReference": "string"
+    },
+    "contacts": [
+      {
+        "contactType": "Account Executive",
+        "referenceSourceName": "string",
+        "referenceSourceId": "string",
+        "contactFirstName": "string",
+        "contactLastName": "string",
+        "addressLine1": "string",
+        "addressLine2": "string",
+        "city": "string",
+        "state": "string",
+        "postalCode": "string",
+        "country": "string",
+        "phoneNumber": "string",
+        "email": "[email protected]",
+        "effectiveDate": "2020-06-09"
+      }
+    ],
+    "timePeriods": [
+      {
+        "dateWindow": {
+          "startDate": "2020-06-09",
+          "endDate": "2020-06-09"
+        },
+        "DOW": {
+          "monday": true,
+          "tuesday": true,
+          "wednesday": true,
+          "thursday": true,
+          "friday": true,
+          "saturday": true,
+          "sunday": true
+        },
+        "timeWindow": {
+          "startTime": "string"
+        }
+      }
+    ],
+    "guidelines": [
+      {
+        "guidelineType": "Content",
+        "excludeOrInclude": "Include",
+        "guidelineId": "string",
+        "guidelineName": "string"
+      }
+    ],
+    "political": false,
+    "inventoryTypes": [
+      "Commercial"
+    ],
+    "maxRate": 1000,
+    "currency": "USD",
+    "externalComment": "Urgent",
+    "audienceSegments": [
+      {
+        "audienceSegmentId": "string",
+        "audienceSegmentName": "string",
+        "audienceSegmentReference": "string",
+        "audienceMethodology": "string",
+        "primaryIndicator": true,
+        "guarantee": true,
+        "ratingSource": "Nielsen",
+        "ratingStream": "Program Live"
+      }
+    ],
+    "pricingMetricOptions": [
+      "CPM"
+    ]
+  }