Create an aspect

Create and deploy aspects for Media Library.

Aspects are sets of properties that describe an asset, and are defined like Studio schemas. Asset managers can apply aspects to assets in the library, with mutations, or programmatically during upload. The information stored in aspects is specific to the Media Library. For local metadata, use fields in your studio projects.

In this guide, you'll create a new aspect and deploy it to your Media Library.

Prerequisites:

• sanity v3.85.1 or later

In a project with a sanity.cli.ts file, edit the configuration to include a mediaLibrary.aspectsPath:

import {defineCliConfig} from 'sanity/cli'

export default defineCliConfig({
  api: {
    projectId: 'YOUR_PROJECT_ID',
    dataset: 'production'
  },
  mediaLibrary: {
    aspectsPath: 'aspects',
  },
  autoUpdates: true,
})

The aspectsPath value is relative to the location of the sanity.cli.ts file.

In the directory you set as aspectsPath, generate a new aspect with the Sanity CLI:

npx sanity@latest media create-aspect

pnpm dlx sanity@latest media create-aspect

yarn dlx sanity@latest media create-aspect

bunx sanity@latest media create-aspect

This command prompts you for a title and a name, then creates a new aspect definition file in your aspects directory. Aspect names must be unique. Whatever you enter is normalized to camel case, so copyright-info becomes copyrightInfo, and the file is written as copyrightInfo.ts.

Aspects can be a single field or an object containing multiple fields. They can contain strings, objects, arrays, or nearly any Studio schema type.

The CLI creates an object-type aspect with a single string field, like this example, where the name is copyright:

import {defineAssetAspect, defineField} from 'sanity'

export default defineAssetAspect({
  name: 'copyright',
  title: 'copyright',
  type: 'object',
  fields: [
    defineField({
      name: 'string',
      title: 'Plain String',
      type: 'string',
    }),
  ],
})

Modify the aspect with more fields. This example updates the existing string field and adds a date type field:

import {defineAssetAspect, defineField} from 'sanity'

export default defineAssetAspect({
  name: 'copyright',
  title: 'copyright',
  type: 'object',
  fields: [
    defineField({
      name: 'copyrightHolder',
      title: 'Copyright Holder',
      type: 'string',
    }),
    defineField({
      name: 'copyrightDate',
      title: 'Date',
      type: 'date',
    }),
  ],
})

Once deployed, the aspect appears in your Media Library like this:

You can see more aspect examples in the aspect patterns cheat sheet.

To query the aspect value from your dataset without authentication, mark the aspect as public:

import {defineAssetAspect, defineField} from 'sanity'

export default defineAssetAspect({
  name: 'copyright',
  title: 'copyright',
  type: 'object',
  fields: [
    defineField({
      name: 'copyrightHolder',
      title: 'Copyright Holder',
      type: 'string',
    }),
    defineField({
      name: 'copyrightDate',
      title: 'Date',
      type: 'date',
    }),
  ],
  public: true
})

When you mark an aspect definition as public, you can resolve its value from your dataset with media::aspect(MEDIA_REF, "ASPECT"), where MEDIA_REF is the asset reference and ASPECT is the aspect name:

*[_type == "post"][0...10] {
  _id,
  title,
  mainImage {
    asset,
    "copyright": media::aspect(media, "copyright")
  }
}

With your aspect defined, it's time to deploy it to your Media Library.

Run the following to deploy a single aspect. Replace copyright with your aspect name:

npx sanity@latest media deploy-aspect copyright

pnpm dlx sanity@latest media deploy-aspect copyright

yarn dlx sanity@latest media deploy-aspect copyright

bunx sanity@latest media deploy-aspect copyright

If you make additional changes to the aspect, you can update it by running the deploy-aspect command again.

To deploy every aspect in your aspects directory, run npx sanity@latest media deploy-aspect --all.

To delete an aspect from your library, run the following command, replacing copyright with the name of your aspect:

npx sanity@latest media delete-aspect copyright

pnpm dlx sanity@latest media delete-aspect copyright

yarn dlx sanity@latest media delete-aspect copyright

bunx sanity@latest media delete-aspect copyright

This deletes the aspect from your library, but doesn't remove the local definition file.