LDraw.org Standards: Official Library Header Specification

Maintained by: The LDraw.org Standards Committee
Writers: Willy Tschager, Travis Cobbs, William Howard
Revision: 9.0, 06 Sep 2007


LDraw Official Library header format suitable for the implementation of the Contributor Agreement (CA).


The header has to identify the LDraw.org username - the basis upon which CA affirmation is assessed - and if the part is covered by the CA or not. It has to conform to the new meta command syntax, where backwards compatibility allows this, as well as structure the history comment lines.


0 PartDescription
0 Name: Filename.dat
0 Author: RealName [UserName]
0 !LDRAW_ORG Part|Subpart|Primitive|8_Primitive|48_Primitive|Shortcut (optional qualifier(s)) ORIGINAL|UPDATE YYYY-RR
0 !LICENSE Redistributable under CCAL version 2.0 : see CAreadme.txt

0 !LICENSE Not redistributable : see NonCAreadme.txt

0 !HELP Optional free text description of file usage
0 !HELP Second row after user's line break to simulate paragraph


0 !CATEGORY Category name
0 !KEYWORDS words, more words,...,
0 !KEYWORDS words in second row, ..., final words

0 !CMDLINE LDraw run-time command(s)

0 !HISTORY YYYY-MM-DD [UserName] Free text description of change. This can wrap to a
0 !HISTORY YYYY-MM-DD [UserName] second row with the same date if necessary. However authors should lean toward writing longer
0 !HISTORY YYYY-MM-DD [UserName] single !HISTORY lines(and not feel constrained to the historic 80-character limit on line length)

0 !HISTORY YYYY-MM-DD {RealName} Free text description of change

0 // Comments

1 <colour> x y z a b c d e f g h i <file>

PartDescription is the descriptive name of the part. If the part is good enough for public use, but has some deficiencies that need to be addressed, the text " (Needs Work)" (without the quotation marks) can be added to the end of the description. If the description includes "(Needs Work)", a comment must be added to the file immediately following the official header describing the work that needs to be done.
is the file name
RealName is the author's real name.
UserName is the author's LDraw username. It needs to be optional for those past authors that still don't have a username.
YYYY-RR is the LDraw update year and release within year.
CAreadme.txt or NonCAreadme.txt is the human readable version of the CCAL added to the parts library package. The square brackets are included in the file to indicate LDraw usernames.

The following meta-commands are optional:
!HELP (Authors should constrain themselves to a 50-character limit to keep the text readable.)
BFC (It is highly recommended to include this statement with a NOCERTIFY for non-BFC certified parts, but not required.)
!CATEGORY (This is required if the first word of the part description isn't in the official category list here: LDraw.org CATEGORY and KEYWORDS Language Extension. Note however, that if CATEGORY is set it has to be one of the listed categories.)

All other meta-commands above are mandatory. No other meta-commands are allowed in the part header.


0 Animal Scorpion
0 Name: 30169.dat
0 Author: Chris Dee [cwdee]
0 !LDRAW_ORG Part UPDATE 2006-01
0 !LICENSE Redistributable under CCAL version 2.0 : see CAreadme.txt

0 !HELP Obviously there is no need for additional
0 !HELP information in this part. But it will give
0 !HELP you an idea of a primitive formatting.
0 !HELP We should limit the length of
0 !HELP a line to 50 characters for the sake of readability.


0 !CATEGORY Animal
0 !KEYWORDS Sting, Poison, Adventurers, Egypt
0 !KEYWORDS Zodiac

0 !CMDLINE -c1

0 !HISTORY 2000-08-?? {Axel Poque} fixes to resolve L3P error messages
0 !HISTORY 2000-08-?? {Manfred Moolhuysen} fixes to resolve L3P error messages,
0 !HISTORY 2000-08-?? {Manfred Moolhuysen} fixed gap where body meets head
0 !HISTORY 2002-04-25 [PTadmin] Official update 2002-02
0 !HISTORY 2004-05-18 [guyvivan] Made BFC compliant
0 !HISTORY 2004-05-18 [guyvivan] Used more primitives
0 !HISTORY 2006-??-?? [PTadmin] Official update 2006-01

0 // Tail
1 16 1 0 23 1 0 0 0 1 0 0 0 1 4-4cyli.dat


0 Boat Base 8 x 10
0 Name: 2622.dat
0 Author: Chris Alano
0 !LDRAW_ORG Part UPDATE 2000-02
0 !LICENSE Not redistributable : see NonCAreadme.txt


0 !KEYWORDS Pirates, Caribbean, Ship

2 24 100 24 80 80 24 20

Appendix I (29-Sep-06)

Format of the !LDRAW_ORG meta-statement suitable for the LDraw Parts Tracker.

0 !LDRAW_ORG Unofficial_Part|Unofficial_Subpart|Unofficial_Primitive|Unofficial_8_Primitive|Unofficial_48_Primitive|Unofficial_Shortcut (optional qualifier(s))

This basically adds the prefix "Unofficial_" to the file type and removes the UPDATE details. It will be implemented within the PT GUI to automate the generation/correction of this line during the sub-mission process by deleting any existing "0 !LDRAW_ORG" line in a submitted file and insert an "0 !LDRAW_ORG Unofficial_..." line in the correct place.

Appendix II (02-Oct-06)

Format of the "~Moved to" files suitable for the implementation of the Contributor Agreement (CA) by using the special username of [PTadmin].


The current format of the "~Moved to" files:

0 ~Moved to {new_number}
0 WRITE Part {old_number} moved to {new_number}
0 BFC CERTIFY CCW 1 16 0 0 0 1 0 0 0 1 0 0 0 1 {new_number}.dat

(where {new_number} and {old_number} are LDraw part numbers)

does not conform to the agreed standard above. It has therefore been changed to the following format.


0 ~Moved to {new_number}
0 Name: {old_number}.dat
0 Author: [PTadmin]
0 !LDRAW_ORG {Part, Subpart, etc as appropriate} (optional qualifier(s)) UPDATE YYYY-RR
0 !LICENSE Redistributable under CCAL version 2.0 : see CAreadme.txt


0 !HISTORY {date} [PTAdmin] {any necessary comment(s)}

0 // {part_description}
1 16 0 0 0 1 0 0 0 1 0 0 0 1 {new_number}.dat


0 ~Moved to 3842a
0 Name: 193a.dat
0 Author: [PTadmin]
0 !LDRAW_ORG Part UPDATE 2006-01
0 !LICENSE Redistributable under CCAL version 2.0 : see CAreadme.txt


0 !HISTORY 2006-12-31 [PTadmin] Official update 2006-01

0 // Minifig Helmet Classic with Thin Chin Guard
1 16 0 0 0 1 0 0 0 1 0 0 0 1 3842a.dat

There is however a possible issue with any programs that use the removed "WRITE" line to update parts.

The new format has been worked out in collaboration with the Parts Tracker Administrators and meets their requirements. The PT GUI submission page will include a check, such that PT authors cannot submit a "~Moved to" file. Implemented should also be a check for existing version of the file against the newly-submitted version, for the case an author changes the title to something other than "~Moved to".

Appendix III (06-Sep-2007)

Optional qualifiers for the !LDRAW_ORG meta-statement


The purpose of the Alias qualifier is to identify a part which is visually identical to another (often caused by LEGO using two different numbers, one for opaque and one for transparent versions of the same part (e.g. 32061), but more recently, there have also been new part numbers for well-established parts - such as brick 2x6
An alias file will typically, but not necessarily, contain only one sub-file reference (line type 1) entry
A file with an Alias type qualifier must not refer to a file that itself has an Alias qualifier.


The purpose of the Physical_Colour qualifier is to identify a part which is encoded as a specific colour of a part (e.g. 70770)
A part file with the Physical_Colour qualifier will typically, but not necessarily, contain only one sub-file reference (line type 1) entry, where the entry has a specific colour value and not colour 16.

0 !LDRAW_ORG Part Alias
0 !LDRAW_ORG Part Physical_Colour

Appendix IV (25-Dec-2015)

Programs relying on the parts.lst file rather then the LDRAW_ORG meta-statement use special characters to prevent the parts being included in the list:

  • The descriptions of all subparts (i.e. line 4 = '0 !LDRAW_ORG Subpart') must start with '~'
  • The description of all obsolete parts, maintained for backwards compatibility must start with '~'
  • The descriptions of all aliases (i.e. line 4 = '0 !LDRAW_ORG Part Alias') must start with '='
  • The descriptions of all physical colour parts (i.e. line 4 = '0 !LDRAW_ORG Part Physical_Colour') should start with '_'

The use of '~' for non "s\" part files is at the author's discretion, to hide mouldings that are not released independently. This is one case where merely reading the LDRAW_ORG line is insufficient for tools to know how to treat the file.

Appendix V (13-Sep-2017)

Optional qualifiers for the !LDRAW_ORG meta-statement


The purpose of the Flexible_Section qualifier is to identify a file in the "parts" folder which represents a subsection of a flexible part. The placement of such files in the "parts" folder allows LDraw users and LDraw applications (such as LSynth) to utilise the subsections to create a flexed rendition of the parent part. Ideally LDraw editing applications should use this qualifier to identify flexible part subsections.

Example: 0 !LDRAW_ORG Part Flexible_Section

Note: This document is an official LSC specification and/or language extension. Material changes can only be made after ratification by the LSC.

Website copyright ©2003-2019 LDraw.org, see Legal Info for details.
LDraw™ is a trademark owned and licensed by the Estate of James Jessiman

LDraw.org is powered by CMS Made Simple.
LEGO® is a registered trademark of the LEGO Group, which does not sponsor, endorse, or authorize this site. Visit the official Lego website at http://www.lego.com.
LDraw is a completely unofficial, community run free CAD system which represents official parts produced by the LEGO company.