FAQ for !CATEGORY and !KEYWORDS meta-statements

This FAQ should get you started with keywords and categories. If you have more questions, please ask on the LDraw forum.

What are '0 !CATEGORY' and '0 !KEYWORDS'?
A: They are two specific meta-statements. Meta-statements are commands in an LDraw file other than the graphics commands. Meta-statements do things like clear the screen, pause momentarily, or display a comment.

Both !CATEGORY and !KEYWORDS are used exclusively in part files and subpart files. They don't appear in models or primitives. They provide information for organizing and searching the part library. Before the !CATEGORY and !KEYWORDS meta-statements were defined, the only way to organize the part library was by the descriptive name and part number. While useful, the name and number do not provide enough information to thoroughly catalog a large directory of parts (currently some 3000 files!).

What is the difference between !CATEGORY and !KEYWORDS, i.e. what belongs to the one and what to the other?
A: !CATEGORY provides a method to place all parts in a comprehensive classification system.

!KEYWORDS provides a method to associate freeform search terms with a part.

!CATEGORY is good for locating a part by drilling into the list of categories. !KEYWORDS are good for locating a part by doing text searches.

The Partsref pages (at http://guide.lugnet.com/partsref/) illustrate how both !KEYWORDS and !CATEGORY can be used. The list of categories on Partsref is based on the !CATEGORY entries in the LDraw parts, and Partsref's Search allows users to search for specific words and terms contained in the !KEYWORDS of parts (as well as their names, numbers, and categories).

What is the syntax for these two meta-statements?

0 !CATEGORY <categoryname>
0 !KEYWORDS <first keyword>, <second keyword>, ..., <last keyword>;

The !CATEGORY meta-statement, if present, must appear in the part header, as defined by the LDraw.org Official Library Header Specification. 

0 Some Part
0 Name: 0000.dat
0 Author: Me
0 !LDRAW_ORG Unofficial_Part

0 !CATEGORY Some
0 !KEYWORDS shape, theme, useful

What is the exact purpose of the "0 !CATEGORY" statement?
A: Their main purpose is to make it easier to find parts in the part library.

More specifically, the 0 !CATEGORY meta-statement provides a way to specify the categorization/classification of parts in the LDraw parts library.

Currently, any program or service that recognizes 0 !CATEGORY uses it as a single-level classification. Whatever text is included after !CATEGORY is used as a single category name.

So if a part contained the statement: 

0 !CATEGORY Minifig Accessory
it would specify that the part belongs in the category "Minifig Accessory".

Are there any "rules" for what you can put in 0 !CATEGORY?
Rule 1. Don't specify any category that doesn't already exist.
Rule 2. If you've got a new part (or several existing parts) that you feel belong(s) in a new category, discuss it on lugnet.cad.dev or e-mail the parts library administrators.

Currently, the 'categories' of the LDraw parts library are mostly limited to the first word in each of the various part names. We will get beyond this, because the descriptive part names should not have to include all the classification information.

It's simpler/easier to have part names like "Minifig Sword" rather than "Minifig Accessory Sword". If a part has a 0 !CATEGORY setting, there is more freedom to give the part a name that is easy to use.

Is it allowed to name more than one category?
A: That wasn't the intent of the 0 !CATEGORY meta-statement. Categories were meant to be a strict classification system, with the long-term possibility of having sub-categories.

As the LDraw parts library continues to grow, the advantages of a multi-level classification system may become more obvious.

Why should category names be restricted to some kind of "official" list?
A: To prevent different people from making up different names/spellings when they mean the same thing, and to avoid completely arbitrary names being used for categories.

Everybody's got their own ideas for classifying LEGO pieces. Some categories are common ('basic brick', 'sloped piece', etc.). But most everyone is going to have some unusual categories for unusual pieces ('gizmo', '>10 studs', etc.) The LDraw classification should avoid these 'unusual' categories, since they tend to be non-intuitive for everyone except the person who thought of them.

Classification will be most useful when there is a balance between the number of categories, the number of parts in each category, and clear definition for each category. If every author defined their own categories, the overall classification would be much less clear.

What is the current list of categories?
A: By default, if a part does not have a !CATEGORY entry, the first word in the part name is used as the category. So the default list of categories is the unique list of words used at the beginning of the part names.

But some of these default categories are less useful than they could be. Some are too narrow/small, such as 'Tap'. Some are not very useful for clear classification, such as 'Town' and 'Space'.

For new parts, the category names should be selected from the following list:

In the near future, this list will be changing, as more parts are deliberately classified. Overall, there should be fewer categories, with a better balance between the categories.

What is the purpose of the 0 !KEYWORDS meta-statement?
A: !KEYWORDS provides a place to put search-text. The 0 !KEYWORDS meta-statement may specify any terms the author feels would be useful in identifying the part, especially terms which are not included in the part's filename, descriptive name, or the !CATEGORY.

Any rules for !KEYWORDS?
Rule 1: Keywords typically include alternate part uses, geometric terms, synonyms (if the part name includes the term "rounded", a keyword might be "curved"), the unique set the part appeared in, and playthemes. Other useful keywords are categories that the part is similar to.
Rule 2: Don't duplicate words and terms from the part name or number.

We should probably start compiling a list of suggested keywords. Just like with categories, having standard keywords will make it easier to locate parts.

Do !KEYWORDS allow multiple entries?
A: Yes, there may be multiple entries on a !KEYWORDS statement. Also, there may be multiple 0 !KEYWORDS meta-statements in a single part file. Each !KEYWORDS meta-statement should be limited to 80 characters.

Entries on a 0 !KEYWORDS meta-statement have to be comma-delimited. Any white-space should be reduced to a single space, and leading and trailing spaces on the keyword ignored.

Each entry can be any string of text. Most search-engines will probably perform searches on all the entries, as a single string of text. So internal delimiters are probably not all that important.

- Manfred Moolhuysen, initial question asker
- Steve Bliss, initial question answerer
- Updated to align with approved file specs - Chris Dee - 15 July 2007