Offical Model Repository Specification

[Roland Melkert]

As requested I forwarded the new Model Repository Specification, see also public threads:

http://forums.ldraw.org/showthread.php?tid=823,823
http://forums.ldraw.org/showthread.php?tid=799,799
http://forums.ldraw.org/showthread.php?tid=740,740
http://forums.ldraw.org/showthread.php?tid=663,663
http://forums.ldraw.org/showthread.php?tid=591,591
http://forums.ldraw.org/showthread.php?tid=412,412
http://forums.ldraw.org/showthread.php?tid=435,435

---------------------------------------------------------------------------

The Offical Model Repository Specification
Version: 1.0.0 Draft
Ratified: XX/XX/XXXX
Author: Orion Pobursky

Purpose:
--------
The Official Model Repository (OMR) is a database of file in the LDraw File Format describing models that are released as sets by LEGO®.

For consistency between models and ease of indexing by software, a standard for the file headers, names, and hierarchy in the OMR is needed. This document will outline the extra requirements (in addition to those set forth in the current LDraw File Format specification) for a model to be included in the OMR

Base Requirements:
------------------
All files in the model will conform to the current LDraw File Format

Base File Naming:
-----------------
Each model in the OMR will consist of several files that are packaged together into a single MPD file. For sets that include instructions for multiple models, each model will have its own MPD file. Each MPD for the set will be named in the following manner:

<Set Number> - <Set Name> - <Sub Model Name>

Where:
<Set Number>: the number assigned on the container of the set
<Set Name>: The name of the set printed on the container in Australian English
<Sub Model Name>: This is Optional in most cases. This is required for alternate models that are detailed in instructions (e.g. the Creator theme). In this case the naming is left to the discretion of the author but should be descriptive of the model contained in the MPD.

For playsets or other sets where there are multiple models that are part of an integral whole, all of the submodels will be contained in one MPD.

Example:
The creator set 4896 - Roaring Roadsters has 3 models in the instructions:
Set 4896 - Roaring Roadsters - Roadster.mpd
Set 4896 - Roaring Roadsters - Dragster.mpd
etc...

MPD File Structure
-------------------
The MPD will conform to the MPD File Specification.

Each filename will have the structure:
<Set Number> - <Optional Qualifier> - <Individual filename>
Where:
<Set Number> is the the number printed on the model's container
<Optional Qualifier> is a sequential number, starting with 1, added if there are more than one sets that could be assigned <Set Number>.
<Individual filename> is up to the discretion of the author with the following guidance:
- A logical naming scheme is highly desired.
- Individual models in the set (e.g. a vehicle or minifig) shall have their own separate file inside the MPD.
- Minifig file name should have the name of the character, if known

The unofficial parts are allowed to be used. The filename of the unofficial part is subject to the naming rules above (e.g. 33056.dat would be renamed to <MPD Filename> - 33956.dat). It is highly encouraged that any parts created for use in a OMR file be submitted to the LDraw.org Parts Tracker.

If a part is unavailable either officially or on the LDraw.org Parts Tracker, a suitable substitution may be made. If the unavailable part is a patterned part with an unpatterned version available use the unpatterned version. A comment should be inserted stating that a substitution has been made or, if no substitution is available/suitable, that a piece has been omitted. Reference the step and page number of the instructions if possible.

Example:
0 // The next piece should have the Star Wars Hatch pattern per step X on page Y
or
0 // Bionicle piece X should go here per step Y on page Z

File Headers
-------------
Each individual model file in the MPD must have a standard header format.

Standard Header:
0 FILE <Filename>.ldr
0 <Individual filename>
0 Name: <Filename>.ldr
0 Author: <Author Name> [Username]
0 !LDRAW_ORG Model -OR- 0 !LDRAW_ORG Unofficial_Model
0 !LICENSE Redistributable under CCAL version 2.0 : see CAreadme.txt

0 !THEME Theme name
0 !KEYWORDS words, more words,…,
0 !KEYWORDS words in second row, …, final words

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)

Where:
<Filename>: The name of the file using the rules specified in the MPD File Structure section
<Individual filename>: The name of the individual file using the rules specified in the MPD File Structure section
<Author Name>: The name of the author. Real full names (first and last) are required by the LDraw.org Contributer's Agreement
[Username]: The LDraw.org username of the author
Optional commands are !THEME, !KEYWORDS, and !HISTORY

Example:
0 FILE 4896 - Roadster Main.ldr
0 Roadster Main
0 Name: 4896 - Roadster Main.ldr
0 Author: Joe Smith [jsmith]
0 !LDRAW_ORG Unofficial_Model
0 !LICENSE Redistributable under CCAL version 2.0 : see CAreadme.txt

0 !THEME Creator
0 !KEYWORDS car, convertible

0 !HISTORY 2011-08-01 [jsmith] Initial creation

META commands:
--------------
All META commands are allowed in the model file but not specifically required except as specified for the header. If included, any META commands used should enable any instructions generated to be as close to the official instructions as possible.

[Travis Cobbs]

I'm mostly OK with the overall document, but below update it with minor corrections and modifications (technical corrections for typos and grammar, replaced etc. with the third concrete model name, added []s around optional items, etc.). I do have some concerns about the content, but will put those in a followup post.

---------------------------------------------------------------------------

The Offical Model Repository Specification
Version: 1.0.0 Draft
Ratified: XX/XX/XXXX
Author: Orion Pobursky

Purpose:
--------
The Official Model Repository (OMR) is a database of files in the LDraw File Format describing models that are released as sets by LEGO®.

For consistency between models and ease of indexing by software, a standard for the file headers, names, and hierarchy in the OMR is needed. This document will outline the extra requirements (in addition to those set forth in the current LDraw File Format specification) for a model to be included in the OMR.

Base Requirements:
------------------
All files in the model will conform to the current LDraw File Format.

Base File Naming:
-----------------
Each model in the OMR will consist of several files that are packaged together into a single MPD file. For sets that include instructions for multiple models, each model will have its own MPD file. Each MPD for the set will be named in the following manner:

<Set Number> - <Set Name>[ - <Sub Model Name>]

Where:
<Set Number>: The number assigned on the container of the set.
<Set Name>: The name of the set printed on the container in Australian English.
<Sub Model Name>: This is Optional in most cases. This is required for alternate models that are detailed in instructions (e.g. the Creator theme). In this case the naming is left to the discretion of the author but should be descriptive of the model contained in the MPD.

For playsets or other sets where there are multiple models that are part of an integral whole, all of the submodels will be contained in one MPD.

Example:
The creator set 4896 - Roaring Roadsters has 3 models in the instructions:
Set 4896 - Roaring Roadsters - Roadster.mpd
Set 4896 - Roaring Roadsters - Dragster.mpd
Set 4896 - Roaring Roadsters - SUV.mpd

MPD File Structure
-------------------
The MPD will conform to the MPD File Specification.

Each filename will have the structure:
<Set Number>[ - <Optional Qualifier>] - <Individual filename>
Where:
<Set Number> is the the number printed on the model's container.
<Optional Qualifier> is a sequential number, starting with 1, added if there is more than one set that could be assigned <Set Number>.
<Individual filename> is up to the discretion of the author with the following guidance:
- A logical naming scheme is highly desired.
- Each individual model in the set (e.g. a vehicle or minifig) shall have its own separate file inside the MPD.
- Minifig file name should have the name of the character, if known.

Unofficial parts are allowed to be used. The filename of the unofficial part is subject to the naming rules above (e.g. 33056.dat would be renamed to <MPD Filename> - 33956.dat). It is highly encouraged that any parts created for use in an OMR file be submitted to the LDraw.org Parts Tracker.

If a part is unavailable either officially or on the LDraw.org Parts Tracker, a suitable substitution may be made. If the unavailable part is a patterned part with an unpatterned version available, use the unpatterned version. A comment should be inserted stating that a substitution has been made or, if no substitution is available/suitable, that a piece has been omitted. Reference the step and page number of the instructions if possible.

Example:
0 // The next piece should have the Star Wars Hatch pattern per step X on page Y
or
0 // Bionicle piece X should go here per step Y on page Z

File Headers
-------------
Each individual model file in the MPD must have a standard header format.

Standard Header:
0 FILE <Filename>.ldr
0 <Individual filename>
0 Name: <Filename>.ldr
0 Author: <Author Name> [Username]
0 !LDRAW_ORG Model -OR- 0 !LDRAW_ORG Unofficial_Model
0 !LICENSE Redistributable under CCAL version 2.0 : see CAreadme.txt

0 !THEME Theme name
0 !KEYWORDS words, more words, …,
0 !KEYWORDS words in second row, …, final words

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).

Where:
<Filename>: The name of the file using the rules specified in the MPD File Structure section
<Individual filename>: The name of the individual file using the rules specified in the MPD File Structure section
<Author Name>: The name of the author. Real full names (first and last) are required by the LDraw.org Contributor's Agreement
[Username]: The LDraw.org username of the author
Optional commands are !THEME, !KEYWORDS, and !HISTORY

Example:
0 FILE 4896 - Roadster Main.ldr
0 Roadster Main
0 Name: 4896 - Roadster Main.ldr
0 Author: Joe Smith [jsmith]
0 !LDRAW_ORG Unofficial_Model
0 !LICENSE Redistributable under CCAL version 2.0 : see CAreadme.txt

0 !THEME Creator
0 !KEYWORDS car, convertible

0 !HISTORY 2011-08-01 [jsmith] Initial creation

META commands:
--------------
All META commands are allowed in the model file but not specifically required except as specified for the header. If included, any META commands used should enable any instructions generated to be as close to the official instructions as possible.

[Travis Cobbs]

As mentioned in my previous post, I have some concerns about the actual contents. Actually, I only really have one concern. The section describing the sub-files in the MPD isn't appropriate for included unofficial parts. I believe that included unofficial parts should be included in the file exactly as they appear on the Parts Tracker (if they are on the Parts Tracker), or exactly as they are supposed to appear on the Parts Tracker (if they are not on the Parts Tracker). So it might look like so:

0 FILE <Filename>.dat
0 ~Electric Mindstorms NXT Battery Lid
0 Name: 54708.dat
0 Author: Philippe Hurbain [Philo]
0 !LDRAW_ORG Unofficial_Part
0 !LICENSE Redistributable under CCAL version 2.0 : see CAreadme.txt

0 BFC CERTIFY CCW

0 !HISTORY 2007-12-07 [Philo] Creation

Where <Filename> is the modified in-the-MPD filename.

[Allen Smith]

> <Set Name>: The name of the set printed on the
> container in Australian English.

Do sets in Australia have names printed on the box? I had thought that naming sets was only done in the Americas. European boxes don't have names on them.

> Unofficial parts are allowed to be used. The
> filename of the unofficial part is subject to the
> naming rules above (e.g. 33056.dat would be
> renamed to <MPD Filename> - 33956.dat).

I agree with Travis that this is an unusual requirement. I suppose mainly it highlights the use of an inlined part in case the number changes while on the part tracker?

* * * *

Other than those two small things, it all looks good.

One last thing: where is the OMR going to be located?

Allen

[Travis Cobbs]

Allen Smith Wrote:
-------------------------------------------------------
> I agree with Travis that this is an unusual
> requirement. I suppose mainly it highlights the
> use of an inlined part in case the number changes
> while on the part tracker?

I wasn't objecting to having the unofficial part get a new name in the MPD, but to the way that it appears in the MPD after that. I meant for "<Filename>" to represent the modified name. There was a discussion on why the parts have to be renamed, and I'm OK with the results of that discussion.

[Roland Melkert]

I agree about having unofficial files unchanged in the mpd. But when the file name is allowed to be different this will conflict with parts using (also embedded) unofficial subparts and or primitives.

So maybe we should only make an unmodified header mandatory?

[Roland Melkert]

After looking at some of the mpd's currently in the official models section, I noticed many use mirroring. I think the standard should address this.

Personally I think it shouldn't be allowed, because it isn't a true representation of the model that way (part lists etc). But I do understand why people do it though.