OpenAPI-Specification.yml

openapi: 3.0.1
info:
  title: Open Meal
  description: ""
  version: "3.4"
paths:
  /distributors:
    get:
      tags:
        - Distributor
      summary: List distributors
      description: This method returns a list of distributors, for example schools and retirement homes
      parameters:
        - name: addressCountry
          in: query
          description: SE - optional parameter used to only get the distributors for a specific country.Use the 2-letter ISO 3166-1 aplha-2 country code, for example "SE" for Sweden
          schema:
            type: string
        - name: searchText
          in: query
          description: Search-text to find specific distributor
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DistributorsListResponse"
  /distributors/{distributorId}:
    get:
      tags:
        - Distributor
      summary: Get distributor
      description: This method returns a single distributor
      parameters:
        - name: distributorId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Distributor"
              examples:
                thelocalschool:
                  value:
                    {
                      "name": "The Local School",
                      "lang": "en",
                      "address":
                        {
                          "streetAddress": "Main Street 42",
                          "postalCode": "555 55",
                          "addressLocality": "Stockholm",
                          "addressCountry": "SE",
                        },
                      "url": "http://thelocalschool.se",
                      "telephone": "+46 555 555 555",
                      "distributorID": "123456789",
                    }
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
  /meals:
    get:
      tags:
        - Meal
      summary: List meals
      description: This method returns a list of meals
      parameters:
        - name: distributorId
          in: query
          description: Parameter specifying the Data Provider ID for a Distributor, used to return only the meals for that distributor.If not provided meals for all distributors are returned
          schema:
            type: string
        - name: lang
          in: query
          description: Get data in a specific language, if omitted default language is used
          schema:
            type: string
        - name: startDate
          in: query
          description: Date specifying the start of the period to get meals for. If not specified, today's date will be used as default.
          schema:
            type: string
            format: date-time
        - name: endDate
          in: query
          description: Date specifying the end of the period to get meals for. If not specified, 7 days after `startDate` will be used as default.
          schema:
            type: string
            format: date-time
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MenuResponse"
              examples:
                meals:
                  value:
                    {
                      "meals":
                        [
                          {
                            "name": "Lunch 1",
                            "date": "2022-06-16",
                            "lang": null,
                            "description": null,
                            "order": 0,
                            "distributor":
                              {
                                "id": "923608a6-e294-4149-ac79-a19f6e7adfd7",
                                "name": "Matkund 1",
                                "organization": Matköping,
                              },
                            "courses":
                              [
                                {
                                  "id": "8f86e3ae-6c42-4ef3-bd32-d3de426ad3ec",
                                  "name": "Fransk pastagratäng med kyckling",
                                  "description": "Krämig pastagratäng med dragonkryddad kyckling och tre sorters ost",
                                  "optionName": "Lunch 1",
                                  "order": 0,
                                  "labelOfContents": "Kycklingfond , GratängOST 28%, Lasagnette, Salt, SENAP Dijon, VispGRÄDDE, Pastakyckling, Paprika röd strimlad, Svartpeppar mald, MellanMJÖLK 1,5% 10L  EKO",
                                  "ingredients":
                                    [
                                      { "name": "Kycklingfond ", "codes": [] },
                                      { "name": "GratängOST 28%", "codes": [] },
                                    ],
                                  "media": [],
                                  "knownAllergens":
                                    [
                                      {
                                        "name": "Selleri",
                                        "codes":
                                          [{ "code": "BC", "type": "GS1" }],
                                      },
                                    ],
                                  "tags": [],
                                  "nutrients":
                                    [
                                      {
                                        "name": "Energi (kJ)",
                                        "amount": 1958.69,
                                        "unit": "kJ",
                                        "codes":
                                          [{ "code": "ENKJ", "type": "GS1" }],
                                      },
                                    ],
                                  "prices":
                                    [
                                      {
                                        "name": "Barn",
                                        "value": 55,
                                        "currency": "SEK",
                                      },
                                      {
                                        "name": "Normal",
                                        "value": 75.95,
                                        "currency": "SEK",
                                      },
                                    ],
                                  "co2Equivalents": 0.58,
                                },
                              ],
                          },
                        ],
                    }
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
components:
  schemas:
    Address:
      type: object
      properties:
        streetAddress:
          type: string
          nullable: true
          description: The street address, including street number
        postalCode:
          type: string
          nullable: true
          description: The postal code without any space, se example
        addressLocality:
          type: string
          nullable: true
          description: The locality, city, of the distributor
        addressRegion:
          type: string
          nullable: true
          description: The region or state, e.g. Ostergotland or Vastra Gotaland, according to SCBs REGINA
        addressCountry:
          type: string
          nullable: true
          description: The 2-letter ISO 3166-1 alpha-2 country code, e.g. SE for Sweden. If data is missing, use data from the dataProvider.
      additionalProperties: false
    Allergen:
      required:
        - codes
      type: object
      properties:
        name:
          type: string
          nullable: true
          description: Name of the allergen
        codes:
          type: array
          items:
            $ref: "#/components/schemas/LookupCode"
          description: List of codes for different lookup databases. Required but can be empty.
      additionalProperties: false
    Course:
      required:
        - ingredients
        - knownAllergens
        - media
        - nutrients
        - prices
        - tags
      type: object
      properties:
        id:
          type: string
          nullable: true
          description: Id of the course
        name:
          type: string
          nullable: true
          description: The name of the course
        description:
          type: string
          nullable: true
          description: Description of the course
        optionName:
          type: string
          nullable: true
          description: The name of the MealOption that refers to the Course
        order:
          type: integer
          format: int32
          description: Used to sort the courses in a preferred order, with lowest order value first.
        labelOfContents:
          type: string
          nullable: true
          description: List ingredients as text. Prebuild label of contents for easier use.
        ingredients:
          type: array
          items:
            $ref: "#/components/schemas/Ingredient"
          description: List of ingredients. Required but can be empty.
        media:
          type: array
          items:
            $ref: "#/components/schemas/Media"
          description: Information about media showcasing the course dishes
        knownAllergens:
          type: array
          items:
            $ref: "#/components/schemas/Allergen"
          description: Describes the allergens of the course by name. Please follow the standard given by your national department/authority for agriculture, food and consumer affairs. See reference for more information. A empty value do not mean there are no allergens, it could just not have been entered. So it shows possible allergens, not definitive.
        tags:
          type: array
          items:
            $ref: "#/components/schemas/Tag"
          description: This array is required and can contain zero or more tags. A empty value do not mean there are no allergens, it could just not have been entered. So it shows possible allergens, not definitive.
        nutrients:
          type: array
          items:
            $ref: "#/components/schemas/Nutrient"
          description: The nutrition values in a standard serving of the course. Strongly recommended. If published as open data, the nutrition values should be referred as by your department for agriculture, food and consumer affairs, in Sweden it is Livsmedelsverket and "Livsmedelsdatabasen", see reference.
        prices:
          type: array
          items:
            $ref: "#/components/schemas/Price"
          description: The price/prices, VAT included, for a course - with the numerical value, currency and name/type as specified by the price item. Can be empty. Strongly recommended.
        co2Equivalents:
          type: number
          format: double
          nullable: true
          description: The amount of CO2-emission per standard portion of this course, maximum of two decimals. Before this is published as open data, the recommendations is to clarify who is the owner of this information and whether or not it is regulated in any contract if it is ok to publish it as open data. For more information about where you can find co2-emissions for food in Sweden, please see reference. Strongly recommended
      additionalProperties: false
    Distributor:
      required:
        - address
        - locations
      type: object
      properties:
        id:
          type: string
          nullable: true
          description: Identifying the distributor within the Data Providers systems, not a unique ID across several data providers. Used to get data for a specific distributor.
        name:
          type: string
          nullable: true
          description: Name of the distributor serving the meal
        organization:
          type: string
          nullable: true
          description: Name of the organisation serving the meal
        lang:
          type: string
          nullable: true
          description: The 2 or 3-letter ISO 639 alpha-2 language code describing the language used in all strings of this object
        type:
          type: string
          nullable: true
          description: Describe the type of the distributor. Six values are valid. 0 = Skola, 1 = Äldreboende, 2 = Hemtjänst, 3 = Sjukhus, 4 = Restaurang, 5 = Övrigt
        address:
          $ref: "#/components/schemas/Address"
          description: The address of the organisation serving the meal. Please note that if option 2 = hemtjänst is selected as type, the adress of the "Hemtjänstkontoret" should be stated and not the adress where hemtjänst is required. This specification is showing the meal information or menu, and not individual orders. Publishing data in this object is strongly recommended.
        locations:
          type: array
          items:
            $ref: "#/components/schemas/Location"
          description: Location in GeoJSON format
        url:
          type: string
          nullable: true
          description: The full URL to the distributor web site. If the distributor does not have a web site it is recommended to refer to the web site of the data provider.
        email:
          type: string
          nullable: true
          description: A contact email address for the organisation according to RFC6068, but do not use the "mailto:"-scheme. See example.
        phone:
          type: string
          nullable: true
          description: A contact phone number for the organisation, including the area code. Do not use any space in order to increase readability and compability with RFC3966.
        iCalendar:
          type: string
          nullable: true
          description: The URL to an iCalender feed with the meal information. For more information about how this is done, see reference.
      additionalProperties: false
    DistributorSummary:
      type: object
      properties:
        id:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
        organization:
          type: string
          nullable: true
      additionalProperties: false
    DistributorsListResponse:
      required:
        - distributors
      type: object
      properties:
        distributors:
          type: array
          items:
            $ref: "#/components/schemas/Distributor"
      additionalProperties: false
    Ingredient:
      required:
        - codes
      type: object
      properties:
        name:
          type: string
          nullable: true
        codes:
          type: array
          items:
            $ref: "#/components/schemas/LookupCode"
      additionalProperties: false
    Location:
      required:
        - geoPositionRepresentations
      type: object
      properties:
        name:
          type: string
          nullable: true
        geoPositionRepresentations:
          type: array
          items:
            $ref: "#/components/schemas/Position"
      additionalProperties: false
    LookupCode:
      type: object
      properties:
        code:
          type: string
          nullable: true
          description: Code for the ingredient for the selected type
        type:
          type: string
          nullable: true
          description: What type of lookup code is used
      additionalProperties: false
    Meal:
      required:
        - courses
        - distributor
      type: object
      properties:
        name:
          type: string
          nullable: true
          description: 'The name of the meal, e.g "Frukost", "Mellanmål" or "Lunch"'
        date:
          type: string
          nullable: true
          description: "The date of the meal in ISO 8601 format with UTC-offset: YYYY-MM-DDTHH:MM:SS+00:00"
        lang:
          type: string
          nullable: true
          description: The 2 or 3-letter ISO 639 alpha-2 language code describing the language used in all strings of this object. To translate menus in many various languages there is a method which uses a free and open licens called qLabel and published at Wikidata. For more information, please see references.
        description:
          type: string
          nullable: true
          description: An optional description of the meal in order to enhance the value of the menu
        order:
          type: integer
          format: int32
          description: Used to sort the meals in a preferred order, with lowest order value first.
        distributor:
          $ref: "#/components/schemas/DistributorSummary"
          description: Information about the distributor of the meal
        courses:
          type: array
          items:
            $ref: "#/components/schemas/Course"
          description: All dishes for the meal including information about allergens, ingredients and nutrition
      additionalProperties: false
    Media:
      type: object
      properties:
        src:
          type: string
          nullable: true
        mimeType:
          type: string
          nullable: true
      additionalProperties: false
    MenuResponse:
      required:
        - meals
      type: object
      properties:
        meals:
          type: array
          items:
            $ref: "#/components/schemas/Meal"
      additionalProperties: false
    Nutrient:
      required:
        - codes
      type: object
      properties:
        name:
          type: string
          nullable: true
        amount:
          type: number
          format: double
        unit:
          type: string
          nullable: true
        codes:
          type: array
          items:
            $ref: "#/components/schemas/LookupCode"
      additionalProperties: false
    Position:
      required:
        - coordinates
      type: object
      properties:
        coordinateSystem:
          type: string
          description: Name of the CoordinateSystem (wgs84)
          nullable: true
        coordinates:
          type: array
          items:
            type: number
            format: double
          description: A pair of Coordinates indicating a point on a map
      additionalProperties: false
    Price:
      required:
        - name
        - value
      type: object
      properties:
        name:
          type: string
          nullable: true
          description: A descriptive label/name for the price item, identifying for instance portion size or similar
        value:
          type: number
          format: double
          description: The cost/amount of the item
        currency:
          type: string
          nullable: false
          description: The three-letter currency code according to ISO 4217 (https://en.wikipedia.org/wiki/ISO_4217). Eg SEK or EUR
      additionalProperties: false
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
      additionalProperties: {}
    Tag:
      required:
        - codes
      type: object
      properties:
        name:
          type: string
          nullable: true
        codes:
          type: array
          items:
            $ref: "#/components/schemas/LookupCode"
      additionalProperties: false