OMR Spec - Official Submission to the LSC

[Orion Pobursky]

LSC,

Below is the final working draft of the OMR Spec submitted for your approval. As a request I would ask that if you significantly change the wording of this draft, please resubmit for public comment.

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

[Roland Melkert]

I've started a thread in the lsc forum.

http://forums.ldraw.org/showthread.php?tid=859,859

[Willy Tschager]

Dear LSC,

please ratify this as quick as possible.

w.

[Orion Pobursky]

Following along with the discussion in the LSC forum, I need to clarify something. The file name requirements in the MPD File Structure section refer to the file name after the FILE and Name: META Commands, not to the noun name of the file (i.e. the first line after the FILE META). The is demonstrated in the header sample but isn't clear in the MPD File Structure section. This means that unofficial parts will have their file names different but not the noun names.

[Travis Cobbs]

Other than the ambiguity about the meaning of <Filename>, my suggested part example does this, unless I'm misunderstanding what you're saying.

[Orion Pobursky]

I'm agreeing with you here. The noun name of the part stays the same, the only thing that changes is the filename. That is the intent of the spec even if it doesn't express it very well.

[Orion Pobursky]

More on that latest discussion by the LSC:

Mirroring, amonst other things, isn't one of those things that's a deal killer for me. Model authors are not parts authors. Most have much, much less knowledge of the nuts and bolts of things. Consequently, my personal standard of measure is much lower for models. Instead of exacting detail, I feel it shoud be "does this model look like what it's trying to represent?". Yes, it would be nice to be able to use OMR models to produce instructions or parts lists but it shouldn't be required.

[Chris Doherty]

really, a curiosity, not a genuine concern. and somehow it's been a month since I looked in this particular forum, so I'm late to the game.

The 8/25 OMR spec update introduced a requirement to use "Australian English" for set names. I didn't see any discussion around that on any OMR spec post. Is there a particular reason to specify which version of English? I'm in the US: I ought to be able to use the name printed on the box I open from which I pull out the instructions I use rather than checking peeron or bricklink or whatever to find out what the same set is called in Australia.

Or, maybe I'm just taking it too literally?

[Orion Pobursky]

James Jessiman, the creator of LDraw, was Australian. Tradition has dictated that we use Australian English spelling in part name (e.g. Tyre vice Tire) so I extended that to the OMR. I thought we specified this somewhere for parts but I can't find that reference right now.

[Tim Gould]

I can't find the references to Australian English either but I know I've seen them before. I've even offered (somewhat tongue-in-cheek) advice before on naming where people used British rather than Australian terms.

There is a little problem with extending it to sets though: Australian sets traditionally don't have a name printed on them. You had to go to the catalogue for that and even that wouldn't guarantee a name.

Tim

[Orion Pobursky]

Hmm. I didn't know that. I just assumed that since the set names are printed in 3 languages here in the US that they would be printed on the set outside the US too. I guess we can change the spec to the official LEGO set name in English, whatever one was/is listed on lego.com or Brickset.

[Chris Dee]

Nowadays, I think set names are unified internationally, but in the 1980s/90s sets often had different names for the US and UK markets. I think this was most prevalent in the Blacktron I and M-Tron ranges. For example 6923 was Particle Ionizer in the US but Cosmicopter in the UK. Even in this era set names were not typically printed on the boxes for the UK market, as the same packaging was probably used across Europe.

Chris

[Chris Dee]

Out of respect for James and what he started I agree that we should continue to use Australian English spelling for part descriptions, because the offcial LEGO names are barely in the public domain and many don't translate well from Danish. Set names, on the other hand are widely known, published in catalogues and of course popularised on Bricklink and peeron. I don't see the value in trying to locate Australian set names.

Chris

[Tim Gould]

I'd take the English set names as being the ones. Certainly where I've had the chance to compare we've always* used the English set names.

Tim

* Except Dino Attack/Dino 2010 where the US sets appeared in our shops while the European sets appeared on S@H. I suspect similar has happened before. Australia is, I believe, officially under the US division of TLG. But our S@H comes from Europe.

[Allen Smith]

Yeah, I had asked about the Australian names in the LSC discussion (probably not the right place for me to have asked, but I'm still getting used to this forum format).

Since set names are (to the best of my knowledge) only printed on boxes distributed in the Americas, I am guessing the U.S. set names are much more widely-known and easier to find than British or Australian variants. I think this specification would be better off preferring U.S. names where available.

Non-U.S. residents please correct me. My rest-of-the-world Lego experience is confined to European sets I've obtained through U.S. S@H.

Allen

[Willy Tschager]

Dear LSC,

one again, please ratify this as quick as possible.

w.

[Jude Parrill]

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

Is it just me, or does it seem extremely redundant to include the THEME, KEYWORDS, and HISTORY for every single submodel of a model? Wouldn't it be more prudent to include this information once in the main model and let that be enough? I understand you are likely basing this off the standards used for .dat files and how each of them often include other files which themselves have their own headers. However, since the entire model is held in a single file, why does it need more than one of these? Considering most parts are often broken up into sections (which may or may not have been worked on by different authors), we don't see this translating into dat files.

And really, when we think about this logically, will a subpart have a different THEME or KEYWORDS from other sub-files? I can't imagine a case when they would. And sure, each subfile could have it's own history, but wouldn't it be much easier to understand the history of the file if it was all located in one spot. For Example:
0 !HISTORY 2011-12-01 [Person1] Created initial file.
0 !HISTORY 2011-12-02 [Person2] Updated subfile m-2aca to line up correctly
0 !HISTORY 2012-12-03 [Person3] Updated subfile m-1ba with missing part included in last update

This paints a much clearer picture the file's history than if the two updates had been put farther down in their respective sub-parts, where they're far less likely to be noticed. By including all the updates in a single place, it's easy to see who did what, when.

[Orion Pobursky]

Per the spec, THEME, HISTORY, and KEYWORDS are optional so if you only want to include them in the main file then that would be perfectly fine.

[Roland Melkert]

One of the reasons for using prefix's in the submodel names was file splitting later on, this goes for the keywords as well.

But like Orion wrote it's the authors choice in the end.

[Willy Tschager]

After creating my first OMR model I believe that:

Code:

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

at:

http://www.ldraw.org/Article593.html

is wrong and that "Set" has to be deleted, changing the "Base File Naming" example to:

Code:

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

w.

[Orion Pobursky]

The word "set" is a typo and wasn't intended... Simple admin edit to remove.

[Michael Heidemann]

With this specification we collidate with the LDraw File Format specification:

File Name
The requirement for LDraw files to conform to the DOS 8.3 filename convention has been removed. Filenames should not exceed 255 characters (including the extension). For reasons of cross-platform and cross-(programming) language portability, the use of white space characters (such as space and tab) in filenames is strongly discouraged. Other special characters, such as &, #, |, and ?, should be avoided as they may also cause cross-platform issues and create problems when used in URLs. It is noted that long filenames and filenames with non-DOS permitted characters may not work with (older) software that does not fully support this specification.

We have to adjust the specs to each other quickly!

mikeheide

[Willy Tschager]

I would change the naming convention in the LDraw File Format specification 1.0.0 with allowing blanks in .ldr and mpd files and keep the restriction solely for official .dat files.

w.

[Michael Heidemann]

Yes, that is also what I was thinking about. It is up to the coming LSC to adjust this quickly.

cu
mikeheide