openapi: '3.0.4'
info:
  title: OpenSpatialWorld API
  description: "The solution allows you to use a web app to enter the associated spatial experience and read and modify aspects of the world. 
    The endpoint provides a single discrete world with some aspects of spatial data management. The main purpose is to join, connect and share the spatial world."
  version: '0.0.1'

servers:
  - url: http://test.openspatialworld.io
    description: static test server with test asset references 
  - url: http://openPortal.openSpatialWolrd.io
    description: dynamic server with dynamic asset refernces

paths:

#--- Web APP ---
  /:
    get:
      tags:
        - web app
      summary: Provisions a web application to deliver the spatial experience on the given device 
      operationId: getDefaultApp
      responses:
        "200": # status code
          description: "web application"
          content:
            text/html:
              schema:
                type: string

#--- World ---
  /wow/world:
    get:
      tags:
        - world
      summary: Returns a World status as a single data state 
      operationId: getWorldStatus
      responses:
        "200": # status code
          description: "world summary"
          content:
            application/json:             
              schema:
                $ref: "#/components/schemas/World"    

#--- User ---
  /wow/user/{userId}:
    get:
      tags:
        - user
      summary: Returns a User status  
      operationId: getUserById
      parameters:
        - name: userId
          in: path
          description: ID of user to return
          required: true
          schema:
            type: integer
      responses:
        "200": # status code
          description: "world summary"
          content:
            application/json:             
              schema:
                $ref: "#/components/schemas/User"
    delete:
      tags:
        - user
      summary: Deletes a user
      operationId: deleteUserById
      parameters:
        - name: userId
          in: path
          description: user id to delete
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: User deleted
        '400':
          description: Invalid user value
        default:
          description: Unexpected error

#--- View ---
  /wow/view/{viewId}:
    get:
      tags: 
        - view
      summary: Returns a Viewpoint status 
      operationId: getViewById
      parameters:
        - name: viewId
          in: path
          description: ID of view to return
          required: true
          schema:
            type: integer
      responses:
        "200": # status code
          description: "world summary"
          content:
            application/json:             
              schema:
                $ref: "#/components/schemas/View"

#--- Portal ---
  /wow/portal/{portalId}:
    get:
      tags: 
        - portal
      summary: Returns a Portal status
      operationId: getPortalById
      parameters:
        - name: portalId
          in: path
          description: ID of portal to return
          required: true
          schema:
            type: integer
      responses:
        "200": # status code
          description: "world summary"
          content:
            application/json:             
              schema:
                $ref: "#/components/schemas/Portal"        

#--- Spatial Composition Graph      

  /wow/spatial/{spatialID}:

    get:
      tags: 
        - Spatial Composition Graph 
      summary: Returns a single Spatial status as a single data state 
      operationId: getSpatialById
      parameters:
        - name: spatialID
          in: path
          description: ID of note to return
          required: true
          schema:
            type: integer
      responses:
        "200": # status code
          description: "world summary"
          content:
            application/json:             
              schema:
                $ref: "#/components/schemas/Spatial"    
  

  /wow/spatial/{spatialID}/node/{nodeId}:

    post:
      tags:
        - Spatial Composition Graph
      summary: Create and add new nodes.
      operationId: addNewNodes
      parameters:
        - name: nodeId
          in: path
          description: ID of existing parent node
          required: true
          schema:
            type: integer
      requestBody:
        description: Created and add single node
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/Node"    
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Node'
        default:
          description: Unexpected error
    get:
      tags: 
        - Spatial Composition Graph 
      summary: Returns a single Node tree as a single data state 
      operationId: getNodeTreeById
      parameters:
        - name: nodeId
          in: path
          description: ID of note to return
          required: true
          schema:
            type: integer
      responses:
        "200": # status code
          description: "world summary"
          content:
            application/json:             
              schema:
                $ref: "#/components/schemas/Node"    
    put:
      tags:
        - Spatial Composition Graph
      summary: Update an existing node.
      operationId: updateNodeById
      parameters:
        - name: nodeId
          in: path
          description: ID of existing parent node
          required: true
          schema:
            type: integer
      requestBody:
        description: Update an existent node 
        content:
          application/json:
            schema:
                $ref: "#/components/schemas/Node"    
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Node"    
        '400':
          description: Invalid ID supplied
        '404':
          description: node not found
        '422':
          description: Validation exception
        default:
          description: Unexpected error
    delete:
      tags:
        - Spatial Composition Graph
      summary: Deletes a node
      operationId: deleteNodeById
      parameters:
        - name: nodeid
          in: path
          description: node id to delete
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: node deleted
        '400':
          description: Invalid node value
        default:
          description: Unexpected error

#------------------   
#--- Components ---
#------------------

components:
  schemas:
    World:
      type: object
      properties:
        content:
          type: object
          properties: 
            label:
              type: string
            age_restriction:
              type: number
            license:
              type: string
            cost: 
              type: string 
            version: 
              type: number 
            duration:
              type: number        
        geoPose:
          type: object
          properties:
            position:
              type: object
              properties:
                lat: 
                  type: number
                lan:
                  type: number
                h:
                  type: number
            angles:
              type: object
              properties:
                yaw:
                  type: number
                pitch:
                  type: number
                roll:
                  type: number
        presence:
          type: object
          properties:
            avatar:
              type: string
            navigation:
              type: string
            gravity:
              type: string
        technology:
          type: object
          properties:
            webXR-immersive:
              type: string
              description: "WebXR session profile"
            runtime:
                type: string
                description: "Web framework or gameengine used (e.g. Unreal or Unity3D)"
        users:
          type: object
          properties:
            active_user_count:
              type: integer
              description: "Number of active"
              default: 1
            total_user_count:
                type: integer
                description: "Total number of user with unique ID"
                default: 1
        views:
          type: object
          properties:
            view_count:
                type: integer
                description: "Number of avalable views with unique ID"
                default: 1
        portals:
          type: object
          properties:
            portal_count:
              type: integer
              description: "Number of available portal with unique ID"
              default: 1

    User: 
      type: object
      properties:
        id: 
          type: number
        name: 
          type: string  
        AvatarURI:
          type: string
        geoPose:
          type: object
          properties:
            position:
              type: object
              properties:
                lat: 
                  type: number
                lan:
                  type: number
                h:
                  type: number
            angles:
              type: object
              properties:
                yaw:
                  type: number
                pitch:
                  type: number
                roll:
                  type: number      

    View: 
      type: object
      properties:
        id: 
          type: number
        geoPose:
          type: object
          properties:
            position:
              type: object
              properties:
                lat: 
                  type: number
                lan:
                  type: number
                h:
                  type: number
            angles:
              type: object
              properties:
                yaw:
                  type: number
                pitch:
                  type: number
                roll:
                  type: number      

    Portal: 
      type: object
      properties:
            
        id: 
          type: number

        geoPose:
          type: object
          properties:
            position:
              type: object
              properties:
                lat: 
                  type: number
                lan:
                  type: number
                h:
                  type: number
            angles:
              type: object
              properties:
                yaw:
                  type: number
                pitch:
                  type: number
                roll:
                  type: number      

    Spatial: 
      type: object
      properties:
            
        id: 
          type: number

        rootNodeID: 
          type: number

        geoPose:
          type: object
          properties:
            position:
              type: object
              properties:
                lat: 
                  type: number
                lan:
                  type: number
                h:
                  type: number
            angles:
              type: object
              properties:
                yaw:
                  type: number
                pitch:
                  type: number
                roll:
                  type: number      

 
    Node: 
      type: object
      properties:
        id: 
          type: integer
        label:
          type: string
        names:
          type: array
          items:
            type: string  
        parent:
          type: integer
        children:
          type: array
          items:
            $ref: '#/components/schemas/Node'
        localTransform:
          type: array 
          items:
            type: number 
        spatialAssetURI:
          type: string
        appearanceURI:
          type: string