swagger: "2.0"
schemes:
  - http
host: api.dataatwork.org
basePath: /v1
info:
  contact:
    name: Work Data Initiative
    url: http://www.dataatwork.org
  description: A complete and standard data store for canonical and emerging skills, knowledge, abilities, tools, technolgies, and how they relate to jobs.
  title: Open Skills API
  version: "1.0"
  x-apisguru-categories:
    - open_data
  x-logo:
    url: https://pbs.twimg.com/profile_images/593962900408008704/WT7rcPhZ_400x400.jpg
  x-origin:
    - format: swagger
      url: http://api.dataatwork.org/v1/spec/skills-api.json
      version: "2.0"
  x-providerName: dataatwork.org
consumes:
  - application/json
produces:
  - application/json
paths:
  /jobs:
    get:
      description: Retrieves the names, descriptions, and UUIDs of all job titles.
      parameters:
        - description: Pagination offset. Default is 0.
          in: query
          name: offset
          type: integer
        - description: Maximum number of items per page. Default is 20 and cannot exceed 500.
          in: query
          name: limit
          type: integer
      responses:
        "200":
          description: A collection of jobs
          schema:
            $ref: "#/definitions/Jobs"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
      summary: Job Titles and Descriptions
  /jobs/autocomplete:
    get:
      description: Retrieves the names, descriptions, and UUIDs of all job titles matching a given search criteria.
      parameters:
        - description: Find job titles beginning with the given text fragment
          in: query
          name: begins_with
          required: false
          type: string
        - description: Find job titles containing the given text fragment
          in: query
          name: contains
          required: false
          type: string
        - description: Find job titles ending with the given text fragment
          in: query
          name: ends_with
          required: false
          type: string
      responses:
        "200":
          description: A collection of jobs
          schema:
            $ref: "#/definitions/Jobs"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
      summary: Job Title Autocomplete
  /jobs/normalize:
    get:
      description: Retrieves the canonical job title for a synonymous job title
      parameters:
        - description: Find the canonical job title(s) for jobs matching the given text fragment
          in: query
          name: job_title
          required: true
          type: string
        - description: Maximumn number of job title synonyms to return. Default is 1 and cannot exceed 10.
          in: query
          name: limit
          required: false
          type: integer
      responses:
        "200":
          description: A collection of normalized jobs
          schema:
            $ref: "#/definitions/NormalizedJobs"
      summary: Job Title Normalization
  /jobs/unusual_titles:
    get:
      description: Retrieves a list of unusual job titles and the UUIDs of their canonical jobs.
      responses:
        "200":
          description: A collection of normalized jobs
          schema:
            $ref: "#/definitions/NormalizedJobs"
      summary: Unusual Job Titles
  "/jobs/{id}":
    get:
      description: Retrieves the name, description, and UUID of a job by specifying its O*NET SOC Code or UUID.
      parameters:
        - description: The O*NET SOC Code or UUID of the job title to retrieve
          in: path
          name: id
          required: true
          type: string
        - description: The FIPS Code of a Core-Based Statistical Area. Only return the job if present in this area
          in: query
          name: fips
          type: string
      responses:
        "200":
          description: A job
          schema:
            $ref: "#/definitions/Job"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
      summary: Job Title and Description
  "/jobs/{id}/related_jobs":
    get:
      description: Retrieves a collection of jobs associated with a specified job.
      parameters:
        - description: The UUID of the job to retrieve related jobs for
          in: path
          name: id
          required: true
          type: string
      responses:
        "200":
          description: A job and its related jobs
          schema:
            $ref: "#/definitions/JobRelatedJobs"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
      summary: Jobs Associated with a Job
  "/jobs/{id}/related_skills":
    get:
      description: Retrieves a collection of skills associated with a specified job.
      parameters:
        - description: The UUID of the job to retrieve skills for
          in: path
          name: id
          required: true
          type: string
      responses:
        "200":
          description: A job and its related skills
          schema:
            $ref: "#/definitions/JobSkills"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
      summary: Skills Associated with a Job
  /skills:
    get:
      description: Retrieve the names, descriptions, and UUIDs of all skills.
      parameters:
        - description: Pagination offset. Default is 0.
          in: query
          name: offset
          type: integer
        - description: Maximum number of items per page. Default is 20 and cannot exceed 500.
          in: query
          name: limit
          type: integer
      responses:
        "200":
          description: A collection of skills
          schema:
            $ref: "#/definitions/Skills"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
      summary: Skill Names and Descriptions
  /skills/autocomplete:
    get:
      description: Retrieves the names, descriptions, and UUIDs of all skills matching a given search criteria.
      parameters:
        - description: Find skill names beginning with the given text fragment
          in: query
          name: begins_with
          required: false
          type: string
        - description: Find skill names containing the given text fragment
          in: query
          name: contains
          required: false
          type: string
        - description: Find skill names ending with the given text fragment
          in: query
          name: ends_with
          required: false
          type: string
      responses:
        "200":
          description: A collection of skills
          schema:
            $ref: "#/definitions/SkillJobs"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
      summary: Skill Name Autocomplete
  /skills/normalize:
    get:
      description: Retrieves the canonical skill name for a synonymous skill name
      parameters:
        - description: Find the canonical skill name(s) for skills matching the given text fragment
          in: query
          name: skill_name
          required: true
          type: string
      responses:
        "200":
          description: A collection of normalized skills
          schema:
            $ref: "#/definitions/NormalizedSkills"
      summary: Skill Name Normalization
  "/skills/{id}":
    get:
      description: Retrieves the name, description, and UUID of a job by specifying its UUID.
      parameters:
        - description: The UUID of the skill name to retrieve
          in: path
          name: id
          required: true
          type: string
      responses:
        "200":
          description: A skill
          schema:
            $ref: "#/definitions/Skill"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
      summary: Skill Name and Description
  "/skills/{id}/related_jobs":
    get:
      description: Retrieves a collection of jobs associated with a specified skill.
      parameters:
        - description: The UUID of the skill to retrieve jobs for
          in: path
          name: id
          required: true
          type: string
      responses:
        "200":
          description: A skill and its related jobs
          schema:
            $ref: "#/definitions/SkillJobs"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
      summary: Jobs Associated with a Skill
  "/skills/{id}/related_skills":
    get:
      description: Retrieves a collection of skills associated with a specified skill.
      parameters:
        - description: The UUID of the skill to retrieve related skills for
          in: path
          name: id
          required: true
          type: string
      responses:
        "200":
          description: A skill and its related skills
          schema:
            $ref: "#/definitions/SkillRelatedSkills"
        default:
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
      summary: Skills Associated with a Skill
definitions:
  Error:
    properties:
      code:
        format: int32
        type: integer
      message:
        type: string
  Job:
    properties:
      normalized_job_title:
        description: Normalized job title
        type: string
      parent_uuid:
        description: UUID for the job's parent job category
        type: string
      title:
        description: Job title
        type: string
      uuid:
        description: Universally Unique Identifier for the job
        type: string
  JobRelatedJob:
    properties:
      parent_uuid:
        description: Universally Unique Identifier for the job's canonical job title
        type: string
      title:
        description: Job title
        type: string
      uuid:
        description: Universally Unique Identifier for the job
        type: string
  JobRelatedJobs:
    properties:
      related_job_titles:
        items:
          $ref: "#/definitions/JobRelatedJob"
        type: array
      uuid:
        description: Universally Unique Identifier for the job
        type: string
  JobSkill:
    properties:
      importance:
        description: O*NET importance score indicating how important skill is to job.
        type: number
      job_title:
        description: Job title
        type: string
      job_uuid:
        description: Universally Unique Identifier for the job
        type: string
      level:
        description: O*NET level score indicating the skill level required for the job.
        type: number
      normalized_job_title:
        description: Normalized job title
        type: string
  JobSkills:
    properties:
      job_title:
        description: Title of the job associated with the UUID
        type: string
      job_uuid:
        description: Universally Unique Identifier for the job
        type: string
      normalized_job_title:
        description: Normalized title of the job associated with the UUID
        type: string
      skills:
        items:
          $ref: "#/definitions/SkillJob"
        type: array
  Jobs:
    items:
      $ref: "#/definitions/Job"
    properties:
      links:
        items:
          $ref: "#/definitions/PageLink"
        type: array
    type: array
  NormalizedJob:
    properties:
      parent_uuid:
        description: Universal Unique Identifier for the canonical job title
        type: string
      relevance_score:
        description: Relevance score for job title.
        type: string
      title:
        description: Job title for the synonymous job title
        type: string
      uuid:
        description: Universally Unique Identifier for the synonymous job title
        type: string
  NormalizedJobs:
    items:
      $ref: "#/definitions/NormalizedJob"
    type: array
  NormalizedSkill:
    properties:
      skill_name:
        description: Canonical skill name
        type: string
      uuid:
        description: Universally Unique Identifier for the canonical skill name
        type: string
  NormalizedSkills:
    items:
      $ref: "#/definitions/NormalizedSkill"
    type: array
  PageLink:
    properties:
      href:
        description: Link URI
        type: string
      rel:
        description: Link descriptor (e.g. self, first, prev, next, last)
        type: string
  Skill:
    properties:
      name:
        description: Skill name
        type: string
      normalized_skill_name:
        description: Normalized skill name
        type: string
      onet_element_id:
        description: O*NET Element Identifier
        type: string
      uuid:
        description: Universally Unique Identifier for the skill
        type: string
  SkillJob:
    properties:
      description:
        description: Description of the skill
        type: string
      importance:
        description: O*NET importance score
        type: number
      level:
        description: O*NET level score
        type: number
      normalized_skill_name:
        description: Normalized skill name
        type: string
      skill_name:
        description: Name of the skill
        type: string
      skill_uuid:
        description: Universally Unique Identifier for the skill
        type: string
  SkillJobs:
    properties:
      jobs:
        items:
          $ref: "#/definitions/JobSkill"
        type: array
      normalized_job_title:
        description: Normalized title of the job associated with the UUID
        type: string
      skill_name:
        description: Title of the job associated with the UUID
        type: string
      skill_uuid:
        description: Universally Unique Identifier for the job
        type: string
  SkillRelatedSkill:
    properties:
      skill_name:
        description: Skill name
        type: string
      uuid:
        description: Universally Unique Identifier for the skill
        type: string
  SkillRelatedSkills:
    properties:
      related_skill_name:
        items:
          $ref: "#/definitions/SkillRelatedSkill"
        type: array
      uuid:
        description: Universally Unique Identifier for the skills
        type: string
  Skills:
    items:
      $ref: "#/definitions/Skill"
    properties:
      links:
        items:
          $ref: "#/definitions/PageLink"
        type: array
    type: array
