openapi: 3.0.0
info:
  version: 1.0.0
  title: Organisation Service
  description: Organisation service and registry

tags:
  - name: OrgServices
    description: Perform operations in organisation with workflow and some customizations (This was planned but not implemented)
  - name: Organisation
    description: Manage organisation details
    

paths:
  /org-services/v1/_create:
    post:
      tags:
        - OrgServices
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrgServiceRequest'
      responses:
        '202':
          description: Accepted create organisation request.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/OrgServiceResponse'
        '400':
          description: Invalid input.
          content:
            '*/*':
              schema:
                $ref: >-
                  https://raw.githubusercontent.com/egovernments/DIGIT-OSS/master/core-services/docs/common-contract_v1-1.yml#/components/schemas/ErrorRes
  /org-services/v1/_update:
    post:
      tags:
        - OrgServices
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrgServiceRequest'
      responses:
        '202':
          description: Accepted update org request.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/OrgServiceResponse'
        '400':
          description: Invalid input.
          content:
            '*/*':
              schema:
                $ref: >-
                  https://raw.githubusercontent.com/egovernments/DIGIT-OSS/master/core-services/docs/common-contract_v1-1.yml#/components/schemas/ErrorRes
  /org-services/v1/_search:
    post:
      tags:
        - OrgServices
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrgSearchCriteria'
      responses:
        '200':
          description: Search organisation response
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/OrgServiceResponse'
        '400':
          description: Invalid input.
          content:
            '*/*':
              schema:
                $ref: >-
                  https://raw.githubusercontent.com/egovernments/DIGIT-OSS/master/core-services/docs/common-contract_v1-1.yml#/components/schemas/ErrorRes
  /org-services/organisation/v1/_create:
    post:
      tags:
        - Organisation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrgRequest'
      responses:
        '202':
          description: Accepted create organisation request.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/OrgResponse'
        '400':
          description: Invalid input.
          content:
            '*/*':
              schema:
                $ref: >-
                  https://raw.githubusercontent.com/egovernments/DIGIT-OSS/master/core-services/docs/common-contract_v1-1.yml#/components/schemas/ErrorRes
  /org-services/organisation/v1/_update:
    post:
      tags:
        - Organisation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrgRequest'
      responses:
        '202':
          description: Accepted update org request.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/OrgResponse'
        '400':
          description: Invalid input.
          content:
            '*/*':
              schema:
                $ref: >-
                  https://raw.githubusercontent.com/egovernments/DIGIT-OSS/master/core-services/docs/common-contract_v1-1.yml#/components/schemas/ErrorRes
  /org-services/organisation/v1/_search:
    post:
      tags:
        - Organisation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrgSearchCriteria'
      responses:
        '200':
          description: Search organisation response
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/OrgServiceResponse'
        '400':
          description: Invalid input.
          content:
            '*/*':
              schema:
                $ref: >-
                  https://raw.githubusercontent.com/egovernments/DIGIT-OSS/master/core-services/docs/common-contract_v1-1.yml#/components/schemas/ErrorRes

components:
  schemas:
    Organisation:
      title: Organisation
      description: Organisation registry
      type: object
      properties:
        id:
          description: Unique identifier of the org
          readOnly: true
          type: string
          format: uuid
        tenantId:
          description: Tenant Identifier
          example: pb.amritsar
          type: string
          minLength: 2
          maxLength: 64
        name:
          description: Name of the org
          type: string
          minLength: 2
          maxLength: 128
        applicationNumber:
          description: Application number for the org registration
          readOnly: true
          type: string
        orgNumber:
          description: Formatted organisation number issued after application is approved
          readOnly: true
          type: string
          minLength: 1
          maxLength: 64
        applicationStatus:
          description: The status of the org
          type: string
          minLength: 2
          maxLength: 64
        externalRefNumber:
          description: ID or code assigned to vendor by the registering department
          type: string
          minLength: 2
          maxLength: 64
        dateOfIncorporation:
          description: Epoch time representing date of incorporation of organisation
          type: number
          format: double
        orgAddress:
          type: array
          items:
            $ref: '#/components/schemas/Address'
        contactDetails:
          description: Contact person information
          type: array
          items:
            $ref: '#/components/schemas/ContactDetails'
        identifiers:
          description: The type of tax identifiers and their values
          type: array
          items:
            $ref: '#/components/schemas/Identifier'
          minItems: 1
        functions:
          description: Functional areas the org works in. Defined in MDMS
          type: array
          items:
            $ref: '#/components/schemas/Function'
          minItems: 1
        jurisdiction:
          description: Unique boundary code list where the org is approved to operate
          type: array
          items:
            $ref: '#/components/schemas/Jurisdiction'
        isActive:
          type: boolean
        documents:
          description: Reference to documents related to the organisation that have been attached via file upload
          type: array
          items:
            $ref: '#/components/schemas/Document'
        additionalDetails:
          description: Json object to capture any extra information which is not accommodated by model
          type: object
        auditDetails:
          $ref: >-
            https://raw.githubusercontent.com/egovernments/DIGIT-OSS/master/core-services/docs/common-contract_v1-1.yml#/components/schemas/AuditDetails
      required:
        - tenantId
        - name
    Identifier:
      title: Identifier
      description: Object to capture tax identifiers for a organisation
      type: object
      properties:
        type:
          description: The type of tax identifier from MDMS data. Eg. PAN, GSTIN, TIN etc..Can be different for other countries
          type: string
          minLength: 2
          maxLength: 64
        value:
          description: Actual value for the identifier.
          type: string
          minLength: 2
          maxLength: 64
        isActive:
          type: boolean
        additionalDetails:
          description: Any additional details that need to be captured
          type: object
    Jurisdiction:
      title: Jurisdiction
      description: Object to capture Jurisdictions for an organisation
      type: object
      properties:
        code:
          description: Jurisdiction code
          type: string
        id:
          description: Jurisdiction id
          type: string
        additionalDetails:
          description: Any additional details that need to be captured
          type: object
    ContactDetails:
      title: ContactDetails
      description: Captures details of a contact person
      type: object
      properties:
        contactName:
          type: string
          minLength: 2
          maxLength: 64
        contactMobileNumber:
          description: Mobile number of the user
          type: string
          maxLength: 20
        contactEmail:
          type: string
          minLength: 5
          maxLength: 200
    Function:
      title: Function
      description: Represents the functions of an organisation
      type: object
      properties:
        orgId:
          description: Organisation UUID
          readOnly: true
          type: string
        applicationNumber:
          description: Application number for the function registration. Will be used in workflow.
          readOnly: true
          type: string
        type:
          description: Type of organisation.Namespaced masters to be defined.
          type: string
          minLength: 2
          maxLength: 64
        category:
          description: Functional area that the org works with.Eg. Electrical, Civil, Mechanical, Stationery etc..
          type: string
          minLength: 2
          maxLength: 64
        class:
          description: Organisation class
          example: Class 1, Class 2, Class 3 etc..
          type: string
          minLength: 2
          maxLength: 64
        validFrom:
          description: Validity from date of registration in epoch time
          type: number
          format: double
        validTo:
          description: Validity to date of registration in epoch time.
          type: number
          format: double
        wfStatus:
          type: string
          minLength: 2
          maxLength: 64
        isActive:
          type: boolean
        applicationStatus: 
          type: string
          enum:
            - ACTIVE
            - INACTIVE
            - INWORKFLOW
        documents:
          description: Reference to documents specifically related to the type and category of work being registered for
          type: array
          items:
            $ref: '#/components/schemas/Document'
        additionalDetails:
          description: Json object to capture any extra information which is not accommodated by model
          type: object
        auditDetails:
          $ref: >-
            https://raw.githubusercontent.com/egovernments/DIGIT-OSS/master/core-services/docs/common-contract_v1-1.yml#/components/schemas/AuditDetails
    OrgServiceRequest:
      title: OrgServiceRequest
      type: object
      properties:
        RequestInfo:
          $ref: >-
            https://raw.githubusercontent.com/egovernments/DIGIT-OSS/master/core-services/docs/common-contract_v1-1.yml#/components/schemas/RequestInfo
        organisations:
          type: object
          allOf:
            - $ref: '#/components/schemas/Organisation'
            - description: Organisation registry
        workflow:
          $ref: 'https://raw.githubusercontent.com/egovernments/DIGIT-OSS/master/core-services/docs/common-contract_v1-1.yml#/components/schemas/Workflow'
    OrgServiceResponse:
      title: OrgServiceResponse
      type: object
      properties:
        ResponseInfo:
          $ref: >-
            https://raw.githubusercontent.com/egovernments/DIGIT-OSS/master/core-services/docs/common-contract_v1-1.yml#/components/schemas/RequestInfo
        organisations:
          type: array
          items:
            $ref: '#/components/schemas/Organisation'
        pagination:
          $ref: 'https://raw.githubusercontent.com/egovernments/DIGIT-OSS/master/core-services/docs/common-contract_v1-1.yml#/components/schemas/Pagination'
        workflow:
          $ref: 'https://raw.githubusercontent.com/egovernments/DIGIT-OSS/master/core-services/docs/common-contract_v1-1.yml#/components/schemas/Workflow'
    OrgSearchCriteria:
      title: OrgSearchCriteria
      description: Organisation search attributes
      type: object
      properties:
        id:
          type: array
          items:
            type: string
            minLength: 2
            maxLength: 64
        tenantId:
          description: Unique tenant of the system
          example: tenantA
          type: string
          minLength: 2
          maxLength: 1000
        name:
          type: string
        applicationNumber:
          type: string
        orgNumber:
          type: string
        applicationStatus:
          type: string
        contactMobileNumber:
          description: Represents Contact Mobile Number
          type: string
        functions:
          type: object
          allOf:
            - $ref: '#/components/schemas/Function'
            - description: Represents the functions of an organisation
        createdFrom:
          type: number
          format: long
        createdTo:
          type: number
          format: long
        boundaryCode:
          type: string
        identifierType:
          type: string
        identifierValue:
          type: string
        includeDeleted:
          description: Used in search APIs to specify if (soft) deleted records should be included in search results.
          type: boolean
          default: false
    OrgRequest:
      title: OrgRequest
      type: object
      properties:
        RequestInfo:
          $ref: >-
            https://raw.githubusercontent.com/egovernments/DIGIT-OSS/master/core-services/docs/common-contract_v1-1.yml#/components/schemas/RequestInfo
        organisations:
          type: object
          allOf:
            - $ref: '#/components/schemas/Organisation'
            - description: Organisation registry
    OrgResponse:
      title: OrgResponse
      type: object
      properties:
        ResponseInfo:
          $ref: >-
            https://raw.githubusercontent.com/egovernments/DIGIT-OSS/master/core-services/docs/common-contract_v1-1.yml#/components/schemas/RequestInfo
        organisations:
          type: array
          items:
            $ref: '#/components/schemas/Organisation'
        pagination:
          $ref: 'https://raw.githubusercontent.com/egovernments/DIGIT-OSS/master/core-services/docs/common-contract_v1-1.yml#/components/schemas/Pagination'
    Address:
      title: Address
      description: Representation of a address. Indiavidual APIs may choose to extend from this using allOf if more details needed to be added in their case.
      type: object
      properties:
        tenantId:
          description: Unique Identifier of the tenant to which user primarily belongs
          type: string
        doorNo:
          description: House number or door number.
          type: string
        plotNo:
          description: Plot number of the house.
          type: string
        id:
          description: System generated id for the address
          readOnly: true
          type: string
        landmark:
          description: additional landmark to help locate the address
          type: string
        city:
          description: City of the address. Can be represented by the tenantid itself
          type: string
        district:
          description: The district in which the property is located
          type: string
        region:
          description: The Region in which the property is located
          type: string
        state:
          description: The State in which the property is located
          type: string
        country:
          description: The country in which the property is located
          type: string
        pincode:
          description: PIN code of the address. Indian pincodes will usually be all numbers.
          type: string
        additionDetails:
          description: more address detail as may be needed
          type: string
        buildingName:
          description: Name of the building
          type: string
          minLength: 2
          maxLength: 64
        street:
          description: Street Name
          type: string
          minLength: 2
          maxLength: 64
        boundaryType:
          description: The boundary type in which the property is located. This refers to the "label" field in boundary-data MDMS eg. Ward, Locality etc.
          type: string
        boundaryCode:
          description: This refers to the boundary code. It can be found in boundary-data MDMS.
          type: string
        geoLocation:
          $ref: '#/components/schemas/GeoLocation'
      required:
        - tenantId
        - locality
    Boundary:
      title: Boundary
      type: object
      properties:
        code:
          description: code of the boundary.
          type: string
        name:
          description: name of the boundary.
          type: string
        label:
          description: localized label for the boundry.
          type: string
        latitude:
          description: latitude of the boundary.
          type: string
        longitude:
          description: longitude of the boundary.
          type: string
        children:
          type: array
          items:
            $ref: '#/components/schemas/Boundary'
        materializedPath:
          description: materialized path of the boundary - this would be of the format tenantid.[code] from parentt till teh current boundary
          readOnly: true
          type: string
      required:
        - code
        - name
    Document:
      title: Document
      description: This object holds list of documents attached during the transaciton for a property
      type: object
      properties:
        id:
          description: system id of the Document.
          type: string
          maxLength: 64
        documentType:
          description: unique document type code, should be validated with document type master
          type: string
        fileStore:
          description: File store reference key.
          type: string
        documentUid:
          description: The unique id(Pancard Number,Adhar etc.) of the given Document.
          type: string
          maxLength: 64
        isActive:
          type: boolean
        additionalDetails:
          description: Json object to capture any extra information which is not accommodated by model
          type: object
    GeoLocation:
      title: GeoLocation
      type: object
      properties:
        latitude:
          description: latitude of the address
          type: number
          format: double
        longitude:
          description: longitude of the address
          type: number
          format: double
        additionalDetails:
          description: Json object to capture any extra information which is not accommodated by model
          type: object