> For the complete documentation index, see [llms.txt](https://docs.learncard.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.learncard.com/core-concepts/credentials-and-data/display-hint-tags.md).

# Display Hint Tags (lc: convention)

LearnCard credentials are **standards-pure** Open Badges v3 / W3C Verifiable Credentials. To let a wallet render a credential more richly — a background color, a certificate-style layout, a friendly subtype label — without adding bespoke fields or custom JSON-LD `@context` terms, LearnCard uses a small, namespaced convention that rides inside the credential's existing, spec-defined `tag` array.

Because these are ordinary tags, any wallet that doesn't understand them simply ignores them. There is **zero interoperability cost** and **zero spec violation**. If other wallets choose to adopt the convention, it becomes a de-facto display micro-standard.

## Where the tags live

Open Badges v3 defines an optional `tag` property on the `Achievement` as an array of strings. Display hints go there:

```json
{
    "credentialSubject": {
        "achievement": {
            "type": ["Achievement"],
            "achievementType": "Achievement",
            "name": "Trailblazer",
            "tag": ["lc:subtype:Trailblazer", "lc:displayType:certificate", "lc:bgColor:353E64"]
        }
    }
}
```

## Format

Each hint is a single string of the form:

```
lc:<key>:<value>
```

* The `lc` namespace and the `<key>` are matched **case-insensitively**.
* Only the **first two colons** are structural. Everything after the second colon is the value, verbatim — so values may themselves contain colons (e.g. a URL).
* Every recognized tag is a **hint, never a requirement**. Unknown keys are ignored, and malformed values (a bad hex color, an unknown display type, a non-`https` URL) are dropped rather than causing an error.

## Recognized keys

| Tag                     | Meaning                                                                                              | Value format                                                      |
| ----------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `lc:category:<name>`    | Credential category. Only accepted if it matches a known LearnCard category.                         | One of the known credential categories (e.g. `Achievement`, `ID`) |
| `lc:subtype:<Label>`    | Human-facing subtype label, shown in place of the coarse category. Decoupled from `achievementType`. | Free text, e.g. `Trailblazer`, `Event`                            |
| `lc:displayType:<type>` | Preferred visual layout                                                                              | One of `badge`, `certificate`, `id`, `course`, `award`, `media`   |
| `lc:bgColor:<hex>`      | Background color                                                                                     | Hex, with or without leading `#` (`353E64` or `#353E64`)          |
| `lc:bgImage:<url>`      | Background image                                                                                     | An `https` URL                                                    |
| `lc:accentColor:<hex>`  | Accent color used for the badge ring and accent text                                                 | Hex, with or without leading `#`                                  |

## Why `subtype` is decoupled from `achievementType`

Earlier LearnCard credentials expressed a badge's flavor by pushing values like `ext:Trailblazer` into the OBv3 `achievementType`. That is spec-legal (the `ext:` prefix is the OBv3 extension convention) but coarse: `achievementType` is meant to describe the *kind* of achievement, not its brand or theme.

With this convention, `achievementType` stays a clean, interoperable spec value (e.g. `Achievement`) and the richer, human-facing label lives in `lc:subtype`. Wallets that understand the convention show the subtype; everyone else still reads a valid, standard credential.

## Precedence

When a wallet resolves a credential's display type, hints are weighted in this order (highest first):

1. An explicit legacy `display.displayType` object (for backwards compatibility with older LearnCard credentials).
2. An `lc:displayType:*` tag.
3. The credential's `achievementType`.
4. The credential's category.

Background color, background image, and accent color resolve the same way: the legacy `display` object wins, then the corresponding `lc:` tag is used as a fallback.

## Backwards compatibility

* Credentials **without** any `lc:` tags behave exactly as before.
* Older credentials that used the internal `display` object continue to render from it; the object wins over the tags.
* Newly issued LearnCard credentials use tags only, keeping the issued credential fully interoperable.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.learncard.com/core-concepts/credentials-and-data/display-hint-tags.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.