Using File Specs

File Specs can be used to specify a list of files, which can be then uploaded or downloaded to or from Artifactory. They are specified in JSON format and are currently supported in JFrog CLI, Jenkins Artifactory Plug-in, TeamCity Artifactory Plug-in, and Bamboo Artifactory Plug-in.

This article describes the File Specs structure used in Jenkins, TeamCity, and the Bamboo Artifactory plugins.You can read about JFrog CLI with File Specs.

The download spec schema offers the option of using AQL or wildcard patterns according to the JSON element you specify:Artifactory Query Language

{
  "files": [
    {
      "pattern" or "aql": "[Mandatory]",
      "target": "[Optional, Default: ./]",
      "props": "[Optional]",
      "recursive": "[Optional, Default: true]",
      "flat": "[Optional, Default: false]",
      "build": "[Optional]",
          "explode": "[Optional, Default: false]",
          "excludePatterns": ["[Optional]"],
          "sortBy" : ["[Optional]"],
      "sortOrder": "[Optional, Default: 'asc']",
      "limit": [Optional],
      "offset": [Optional]
    }
  ]
}

Where:

{
  "files": [
    {
      "pattern": "[Mandatory]",
      "target": "[Mandatory]",
      "props": "[Optional]",
      "recursive": "[Optional, Default: 'true']",
      "flat" : "[Optional, Default: 'true']",
      "regexp": "[Optional, Default: 'false']",
      "explode": "[Optional, Default: false]",
          "excludePatterns": ["[Optional]"]
    }
  ]
}

Where:

File Specs offer enormous flexibility in how you upload, or download files through use of wildcard or regular expressions with placeholders.

Any wildcard enclosed in parenthesis in the pattern property can be matched with a corresponding placeholder in the target property to determine the name of the artifact once downloaded or uploaded. The following example downloads all zip files, located under the root path of the my-local-repo repository, which include a dash in their name. The files are renamed when they are downloaded, replacing the dash with two dashes.

{
    "files": [
        {
            "pattern": "my-local-repo/(*)-(*).zip",
            "target": "froggy/{1}--{2}.zip",
                        "recursive": "false"
        }
    ]
}

Example 1: Download all files located under the all-my-frogs directory in the my-local-repo repository to the froggy/all-my-frogs directory.

{
    "files": [
        {
            "pattern": "my-local-repo/all-my-frogs/",
            "target": "froggy/"
        }
    ]
}

Example 2: Download all files retrieved by the AQL query to the local/output directory.

{
  "files": [
    {
      "aql": {
        "items.find": {
          "repo": "my-local-repo",
          "$or": [
            {
              "$and": [
                {
                  "path": {
                    "$match": "."
                  },
                  "name": {
                    "$match": "a1.in"
                  }
                }
              ]
            },
            {
              "$and": [
                {
                  "path": {
                    "$match": "*"
                  },
                  "name": {
                    "$match": "a1.in"
                  }
                }
              ]
            }
          ]
        }
      },
      "target": "local/output/"
    }
  ]
}

Example 3: Upload

{
  "files": [
    {
      "pattern": "resources/*.zip",
      "target": "my-repo/zip/",
      "props": "type=zip;status=ready"
    },
    {
      "pattern": "resources/*.tgz",
      "target": "my-repo/tgz/",
          "props": "type=tgz;status=ready"
    }
  ]
}

Example 4: Download all files located under the all-my-frogs directory in the my-local-repo repository except for the '.zip' files and the 'props.' files

{
  "files": [
    {
      "pattern": "my-local-repo/all-my-frogs/",
          "excludePatterns": [
                "*.zip", 
                "all-my-frogs/props.*"
                ]
    }
  ]
}

Example 5: Download the three oldest zip files from the my-local-repo repository, into local/output directory.

{
  "files": [
    {
      "pattern": "my-local-repo/*.zip",
      "sortBy": ["created"],
      "limit": 3,
      "target": "local/output/"
    }
  ]
}

Example 6: Download the three oldest zip files from the my-local-repo repository, into local/output directory. This File Spec uses AQL.

{
  "files": [
    {
      "aql": {
        "items.find": {
          "repo": "my-local-repo",
          "$or": [
            {
              "$and": [
                {
                  "path": {
                    "$match": "*"
                  },
                  "name": {
                    "$match": "*.zip"
                  }
                }
              ]
            }
          ]
        }
      },
      "sortBy": ["created"],
      "limit": 3,
      "target": "local/output/"
    }
  ]
}

Example 7: Download the artifacts from the generic-local repository, which belong to the following build, which had been published to Artifactory - Build name: my-build and build number: 10.

{
  "files": [
    {
      "pattern": "generic-local",
      "build": "my-build/10"
    }
  ]
}

Example 8: Download the artifacts from the generic-local repository, which belong to the my-build build, which had been published to Artifactory. The artifacts of the latest build number published to Artifactory will be downloaded.

{
  "files": [
    {
      "pattern": "generic-local",
      "build": "my-build"
    }
  ]
}

JSON schemasallow you to annotate and validate JSON files. The JFrog File Spec schema is available in the JSON Schema Store catalog and in the following link: https://github.com/jfrog/jfrog-cli/blob/v2/schema/filespec-schema.json.

Using Jetbrains IDEs (Intellij IDEA, Webstorm, Goland, etc...)?

The File Spec schema automatically applied on the following file patterns:

**/filespecs/*.json
*filespec*.json
*.filespec

Using Visual Studio Code?

To apply the File Spec schema validation, install the JFrog VS-Code extension.

Alternatively, copy the following to your settings.json file:

settings.json

"json.schemas": [
  {
    "fileMatch": ["**/filespecs/*.json", "*filespec*.json", "*.filespec"],
    "url": "https://raw.githubusercontent.com/jfrog/jfrog-cli/v2/schema/filespec-schema.json"
  }
]