Table of Contents

What are you trying to do?


Add Model Metadata

If you are a Standard Development Organization (SDO), an open source project, or an organization such as a vendor that creates proprietary models, and you want to add your models' metadata to the Catalog, do the following. NOTE: the Catalog is not a clearing house for model downloads. While it provides metadata about models, it only provides links to external sites from which the models themselves can be download.

  1. Check your modules into GitHub. Ideally submit your modules directly to the https://github.com/YangModels/yang repository via a pull request. Alternatively, you can use any public repository, and then also add a git sub-module to the https://github.com/YangModels/yang repository via a pull request.
  2. Request a new YANG Catalog API account if you do not have one already.
  3. Once the account is requested, wait until confirmation before proceeding.
  4. Use an HTTP PUT request to https://yangcatalog.org:8443/modules with a JSON payload modeled after the model-metadata.yang model (current revision: 2017-07-27). Note, this module requires the yang-catalog module. The module-metadata.yang has the following tree structure:
    module: module-metadata
        +--rw modules
           +--rw module* [name revision organization]
              +--rw name                     yang:yang-identifier
              +--rw revision                 union
              +--rw generated-from?          enumeration
              +--rw maturity-level?          enumeration
              +--rw document-name?           string
              +--rw author-email?            yc:email-address
              +--rw reference?               inet:uri
              +--rw module-classification    enumeration
              +--rw organization             string
              +--rw ietf
              |  +--rw ietf-wg?   string
              +--rw source-file
                 +--rw owner         string
                 +--rw repository    string
                 +--rw path          path
                 +--rw branch?       string
    
    For example:
    PUT https://yangcatalog.org:8443/modules
    Content-type: application/json
    
      {
          "modules": {
             "module": [
             {
               "name": "example-jukebox",
               "revision": "2014-01-20",
               "organization": "example",
               "maturity-level": "ratified",
               "author-email": "foo@bar.com",
               "module-classification": "network-element",
               "source-file": {
                 "repository": "foo",
                 "owner": "bar",
                 "path": "standard/ietf/DRAFT/example-jukebox.yang"
               }
             }
           ]
         }
      }
    
  5. After submitting the request, if you are authorized, you will receive a job ID in the JSON-formatted reply. For example:
      {
        "info": "Verification successful",
        "job-id": "88bd8c4c-8809-4de8-85c8-39d522d4bcdf"
      }
    
  6. Perform an HTTP GET request to https://yangcatalog.org:8443/job/{job_id} to get the status of the job. The job result will remain "In progress" until the job completes. When the job has completed you will receive either a "Finished" (on success) or "Failed" (on failure) result. Reason will remain null if the result is other then "Failed, otherwise it will give a information on why it failed. For example, after obtaining the job ID above, perform an HTTP GET to https://yangcatalog.org:8443/job/88bd8c4c-8809-4de8-85c8-39d522d4bcdf to get the current status:
      {
        "info": {
          "job-id": "88bd8c4c-8809-4de8-85c8-39d522d4bcdf",
          "reason": null,
          "result": "In progress"
        }
      }
    
  7. Once the job has completed successfully, test the result by querying the search API.
  8. Contact info@yangcatalog.org if you run into problems.

While some metadata can be extracted from models by the API backend (these are called extractable fields), metadata such as "maturity-level" and "conformance-type" must be provided by the model creator (these are the non-extractable fields). The reason the module-metadata model is broken out from the main yang-catalog module is to focus more on the non-extractable fields. The more metadata from the module-metadata model that can be included the more robust and detailed the Catalog will be.

Add Implementation Metadata

If you are a vendor that implements YANG models in your product, then you can upload platform metadata to the Catalog in order to specify what platforms (and software releases) implement which YANG models. This is done using the following steps:

  1. Request a new YANG Catalog API account if you do not have one already.
  2. Once the account is requested, wait until confirmation before proceeding.
  3. Use an HTTP PUT request to https://yangcatalog.org:8443/platforms with a JSON payload modeled after the platform-implementation-metadata.yang model (current revision: 2017-09-27). Note, his module requires the yang-catalog module. The platform-implementation-metadata module has the following tree structure:
     module: platform-implementation-metadata
         +--rw platforms
            +--rw platform* [vendor name software-version software-flavor]
               +--rw vendor                  string
               +--rw name                    string
               +--rw netconf-capabilities*   string
               +--rw product-ids*            string
               +--rw software-version        string
               +--rw software-flavor         string
               +--rw os-version?             string
               +--rw feature-set?            string
               +--rw os-type?                string
               +--rw module-list-file
                  +--rw type?         enumeration
                  +--rw owner         string
                  +--rw repository    string
                  +--rw path          yc:path
                  +--rw branch?       string
         
    For example:
         PUT https://yangcatalog.org:8443/platforms
         Content-type: application/json
    
         {
           "platforms" {
               "platform": [
                   {
                      "vendor": "example",
                      "name": "baz",
                      "module-list-file": {
                         "type": "capabilities",
                         "repository": "foo",
                         "owner": "bar",
                         "path": "vendor/example/baz/baz-netconf-capability.xml"
                      },
                      "platform-ids": [
                         "BAZ4000", "BAZ4100"
                      ],
                      "software-flavor": "ALL",
                      "software-version": "1.2.3",
                      "os-type": "bazOS"
                    }
               ]
           }
        }
         
  4. After submitting the request, if you are authorized, you will receive a job ID in the JSON-formatted reply. For example:
    {
      "info": "Verification successful",
      "job-id": "88bd8c4c-8809-4de8-85c8-39d522d4bcdf"
    }
    
  5. Perform an HTTP GET request to https://yangcatalog.org:8443/job/{job_id} to get the status of the job. The job result will remain "In progress" until the job completes. When the job has completed you will receive either a "Finished" (on success) or "Failed" (on failure) result. For example, after obtaining the job ID above, perform an HTTP GET to https://yangcatalog.org:8443/job/88bd8c4c-8809-4de8-85c8-39d522d4bcdf to get the current status:
    {
      "info": {
        "job-id": "88bd8c4c-8809-4de8-85c8-39d522d4bcdf",
        "reason": null,
        "result": "In progress"
      }
    }
    
  6. Once the job has completed successfully, test the result by querying the search API.
  7. Contact info@yangcatalog.org if you run into problems.
Get Module and Implementation Metadata

If you want to search for metadata on a specific module, or you are looking for modules that contain specific metadata, you can do the following:

  1. Use an HTTP GET request to https://yangcatalog.org:8443/search/modules/{name},{revision},{organization} to receive all the metadata for a specific module and revision.
  2. Use an HTTP GET request to https://yangcatalog.org:8443/search/{key}/{value} to receive all the modules that contain a specific metadata.
    For example, to find all modules with a successful compilation status: https://yangcatalog.org:8443/search/compilation-status/passed
    To find all modules from the netconf working group in the IETF: https://yangcatalog.org:8443/search/ietf/ietf-wg/netconf
    This method will work for any node within the yang-catalog:
    module: yang-catalog
    <<<<<<< HEAD
    +--rw catalog
     +--rw modules
     |  +--rw module* [name revision organization]
     |     +--rw name                        yang:yang-identifier
     |     +--rw revision                    union
     |     +--rw organization                string
     |     +--rw ietf
     |     |  +--rw ietf-wg?   string
     |     +--rw namespace                   inet:uri
     |     +--rw schema?                     inet:uri
     |     +--rw generated-from?             enumeration
     |     +--rw maturity-level?             enumeration
     |     +--rw document-name?              string
     |     +--rw author-email?               yc:email-address
     |     +--rw reference?                  inet:uri
     |     +--rw module-classification       enumeration
     |     +--rw compilation-status?         enumeration
     |     +--rw compilation-result?         inet:uri
     |     +--rw prefix?                     string
     |     +--rw yang-version?               enumeration
     |     +--rw description?                string
     |     +--rw contact?                    string
     |     +--rw module-type?                enumeration
     |     +--rw belongs-to?                 yang:yang-identifier
     |     +--rw tree-type?                  enumeration
     |     +--rw submodule* [name revision]
     |     |  +--rw name        yang:yang-identifier
     |     |  +--rw revision    union
     |     |  +--rw schema?     inet:uri
     |     +--rw dependencies* [name]
     |     |  +--rw name        yang:yang-identifier
     |     |  +--rw revision?   union
     |     |  +--rw schema?     inet:uri
     |     +--rw dependents* [name]
     |     |  +--rw name        yang:yang-identifier
     |     |  +--rw revision?   union
     |     |  +--rw schema?     inet:uri
     |     +--rw semantic-version?           yc:semver
     |     +--rw derived-semantic-version?   yc:semver
     |     +--rw implementations
     |        +--rw implementation*
     |                [vendor platform software-version software-flavor]
     |           +--rw vendor              string
     |           +--rw platform            string
     |           +--rw software-version    string
     |           +--rw software-flavor     string
     |           +--rw os-version?         string
     |           +--rw feature-set?        string
     |           +--rw os-type?            string
     |           +--rw feature*            yang:yang-identifier
     |           +--rw deviation* [name revision]
     |           |  +--rw name        yang:yang-identifier
     |           |  +--rw revision    union
     |           +--rw conformance-type?   enumeration
     +--rw vendors
        +--rw vendor* [name]
           +--rw name         string
           +--rw platforms
              +--rw platform* [name]
                 +--rw name                 string
                 +--rw software-versions
                    +--rw software-version* [name]
                       +--rw name                string
                       +--rw software-flavors
                          +--rw software-flavor* [name]
                             +--rw name         string
                             +--rw protocols
                             |  +--rw protocol* [name]
                             |     +--rw name
                             |     |       identityref
                             |     +--rw protocol-version*   string
                             |     +--rw capabilities*       string
                             +--rw modules
                                +--rw module*
                                        [name revision organization]
                                   +--rw name                leafref
                                   +--rw revision            leafref
                                   +--rw organization        leafref
                                   +--rw os-version?         string
                                   +--rw feature-set?        string
                                   +--rw os-type?            string
                                   +--rw feature*
                                   |       yang:yang-identifier
                                   +--rw deviation* [name revision]
                                   |  +--rw name
                                   |  |       yang:yang-identifier
                                   |  +--rw revision    union
                                   +--rw conformance-type?
                                           enumeration
    =======
        +--rw catalog
           +--rw modules
           |  +--rw module* [name revision organization]
           |     +--rw name                     yang:yang-identifier
           |     +--rw revision                 union
           |     +--rw organization             string
           |     +--rw ietf
           |     |  +--rw ietf-wg?   string
           |     +--rw namespace                inet:uri
           |     +--rw schema?                  inet:uri
           |     +--rw generated-from?          enumeration
           |     +--rw maturity-level?          enumeration
           |     +--rw document-name?           string
           |     +--rw author-email?            yc:email-address
           |     +--rw reference?               inet:uri
           |     +--rw module-classification    enumeration
           |     +--rw compilation-status?      enumeration
           |     +--rw compilation-result?      inet:uri
           |     +--rw prefix?                  string
           |     +--rw yang-version?            enumeration
           |     +--rw description?             string
           |     +--rw contact?                 string
           |     +--rw module-type?             enumeration
           |     +--rw belongs-to?              yang:yang-identifier
           |     +--rw tree-type?               enumeration
           |     +--rw submodule* [name revision]
           |     |  +--rw name        yang:yang-identifier
           |     |  +--rw revision    union
           |     |  +--rw schema?     inet:uri
           |     +--rw dependencies* [name]
           |     |  +--rw name        yang:yang-identifier
           |     |  +--rw revision?   union
           |     |  +--rw schema?     inet:uri
           |     +--rw dependents* [name]
           |     |  +--rw name        yang:yang-identifier
           |     |  +--rw revision?   union
           |     |  +--rw schema?     inet:uri
           |     +--rw semantic-version?           yc:semver
           |     +--rw derived-semantic-version?   yc:semver
           |     +--rw implementations
           |        +--rw implementation* [vendor platform software-version software-flavor]
           |           +--rw vendor              string
           |           +--rw platform            string
           |           +--rw software-version    string
           |           +--rw software-flavor     string
           |           +--rw os-version?         string
           |           +--rw feature-set?        string
           |           +--rw os-type?            string
           |           +--rw feature*            yang:yang-identifier
           |           +--rw deviation* [name revision]
           |           |  +--rw name        yang:yang-identifier
           |           |  +--rw revision    union
           |           +--rw conformance-type?   enumeration
           +--rw vendors
              +--rw vendor* [name]
                 +--rw name         string
                 +--rw platforms
                    +--rw platform* [name]
                       +--rw name                 string
                       +--rw software-versions
                          +--rw software-version* [name]
                             +--rw name                string
                             +--rw software-flavors
                                +--rw software-flavor* [name]
                                   +--rw name         string
                                   +--rw protocols
                                   |  +--rw protocol* [name]
                                   |     +--rw name                identityref
                                   |     +--rw protocol-version*   string
                                   |     +--rw capabilities*       string
                                   +--rw modules
                                      +--rw module* [name revision organization]
                                         +--rw name                -> /catalog/modules/module/name
                                         +--rw revision            -> /catalog/modules/module/revision
                                         +--rw organization        -> /catalog/modules/module/organization
                                         +--rw os-version?         string
                                         +--rw feature-set?        string
                                         +--rw os-type?            string
                                         +--rw feature*            yang:yang-identifier
                                         +--rw deviation* [name revision]
                                         |  +--rw name        yang:yang-identifier
                                         |  +--rw revision    union
                                         +--rw conformance-type?   enumeration
    >>>>>>> e5ff454e7b1569289a6a870683a4f7a60d569ecd
                     
Delete Module Metadata

If you need to delete metadata relative to one of your specific modules, do the following:

  1. Request a new YANG Catalog API account if you do not have one already.
  2. Once the account is requested, wait until confirmation before proceeding.
  3. Use an HTTP DELETE request to delete specific module https://yangcatalog.org:8443/modules/module/{name},{revision},{organization}
  4. Use an HTTP DELETE request to delete modules on specific implementation metadata https://yangcatalog.org:8443/vendors/vendor/{name}. You can continue deeper on the vendors branch up to software-flavor

NOTE: Deleting implementation metadata is currently not possible.

Hacking Yangcatalog.org

All of the code behind yangcatalog.org is Open Source. However, it is spread out across multiple GitHub repositories. If you are interested in hacking the code that directly drives the YANG Catalog, pick your repository from the list below:

In order to contribute back to YANG Catalog, checkout one of the repositories, make your changes, and then create a pull request to have your code merged.

To get updates about changes with YANG Catalog, subscribe to announce@yangcatalog.org.