Documentation

A manual can describe a collection of guides, or just a single guide. An example service manual for a Dell laptop might include a dozen guides, technical descriptions of the device, or hundreds of photos and videos. The manual could be accessed by reading a .omanual file on a desktop computer, or on a tablet or smartphone via a web service.

The common oManual data format can be expressed as XML (useful for interoperability with legacy data in formats such as DITA) or made available over a web API using mobile-friendly JSON.

Data Specification

Category Documentation XML Schema Definition Example XML Example JSON

This document describes category metadata. A category can be anything you would write step-by-step procedures about, such as a manufactured object, or device. This also includes a list of guides in the package and a list of attached documents in the /media folder.

Note: This is not a complete listing of package contents since each subfile may additionally reference its own media.

required
optional

category

The root of an oManual category.

  • Attributes:
  • locale - required The language the package is written in.

title

Contains the title of the category document (which may differ from the category name).

  • Attributes: None

category_info

Text should contain the canonical name of the category.

  • Attributes:
  • manufacturer - optional Only relevant for devices. The canonical name of the device's manufacturer.
  • introduced - optional Only relevant for devices. The date (ISO 8601 date in the format YYYY-MM-DDThh:mm:ssTZD) that the device was first sold.
  • discontinued - optional Only relevant for devices. The date (ISO 8601 date in the format YYYY-MM-DDThh:mm:ssTZD) that the device was discontinued. If the device is still available, leave the attribute empty.

image

Path to an image of the category, relative to this file.

  • Attributes: None

description

A brief, simple HTML formatted description of the category.

  • Attributes: None

flags

  • Attributes: None

flag

A flag or informational note about the category. The text field contains a full text notice of what this flag means to the user.

  • Attributes:
  • id - optional A unique identifier for the flag.
  • title - required A short title for the flag. ex: In Progress
  • image optional URI of an image to go along with the flag, no larger than 44x44.

ancestors

List of categories, in descending order, to which the category belongs.

  • Attributes: None

ancestor

A single category the category belongs to. There is not currently a global list of documentation categories.

  • Attributes: None

children

List of categories that have this category as a parent. For example, an "MP3 Player" category could have "iPod", "Zune", etc as children.

  • Attributes: None

child

The category name of the child belonging to this category.

  • Attributes: None

documents

  • Attributes: None

document

A document included in the package. The text for this element should be the path to the document.

  • Attributes:
  • id - optional Integer identifier for the document.
  • type - optional The MIME type of the file.
  • date - optional ISO 8601 date in the format YYYY-MM-DDThh:mm:ssTZD. Last modified date of the document.

solutions

A reference to an external mailing list, Q&A site, message board - anywhere your audience can find additional troubleshooting information. For example, iFixit Answers and Stack Overflow are two examples of solution providers.

  • Attributes:
  • count optional Number of solutions available about this category.
  • url optional URL to the category-specific solutions.

tools

  • Attributes: None

tool

A required or suggested tool/implement. Use a name common to all of your guides and specify variations using the type attribute.

  • Attributes:
  • type optional The type of tool. Specifying type can be a useful way of consolidating tool names, for example an 8mm socket could be specified as name: socket, type: 8mm.
  • quantity optional Integer quantity of tool required. If omitted, this is assumed to be 1.
  • notes optional Information specific to using this tool for this guide.
  • thumbnail optional Path to an image to go along with the tool.
  • url optional A URL for an external reference describing the tool.
  • sku optional The manufacturer SKU / part number.

parts

  • Attributes: None

part

A part, material, or ingredient used in this category.

  • Attributes:
  • sku optional A global string identifier for the part.
  • type optional The type of part. Specifying type can be a useful way of consolidating names, for example a 5Ω resistor could be specified as name: resistor, type: 5Ω.
  • quantity optional How many of this part are required.
  • thumbnail optional URI of an image to go along with the part.
  • url optional A URL for a page describing the part.
  • notes optional Information specific to using this part for this guide.

contents

Simple HTML-formatted text of the document. This is not required, but is an opportunity to provide additional unstructured information about the category.

  • Attributes: None

guides

List of guides about the category.

  • Attributes: None

guide

Individual guide element. A short description of the guide that's contained within the oManual package. The corresponding file in the package has the filename guide-{id}.xml.

  • Attributes:
  • id - required An integer identifier for the guide.
  • subject - required The subcomponent the guide will be operating on.
  • type - required The type of guide to perform. Suggested options: installation, maintenance, repair, disassembly, technique.

title

The title of the guide.

  • Attributes: None

path

Path to the guide.

  • Attributes: None

url

URL to the canonical online source for this guide.

  • Attributes: None

image

Path to the main category image.

  • Attributes:
  • mini optional Path to a thumbnail of the image no larger than 56x42.
  • thumbnail optional Path to a thumbnail of the image no larger than 96x72.
  • standard optional Path to a thumbnail of the image no larger than 300x225.
  • medium optional Path to a thumbnail of the image no larger than 592x444.
  • large optional Path to a thumbnail of the image no larger than 800x600.

Guide Documentation XML Schema Definition Example XML Example JSON

A guide is a structured collection of steps. Each must include text and media. For consistency of display, we recommend each step consist of 1-3 images or one rich media object, as well as no more than eight lines of text.

required
optional

guide

The root of an oManual guide.

  • Attributes:
  • locale required The language the guide is written in.

modified_date

ISO 8601 date in the format YYYY-MM-DDThh:mm:ssTZD - Date and time this guide was last updated. This element can be useful for checking if there are updates to the guide. The modified_date is the same as the created_on date in a new guide.

  • Attributes: None

created_date

ISO 8601 date in the format YYYY-MM-DDThh:mm:ssTZD - Date and time when this guide was first created.

  • Attributes: None

title

Contains the title of the guide.

  • Attributes:
  • subject optional The subject of the guide. ex: Bottom Bezel Bracket
  • type optional What the guide explains in relation to the subject. ex: Installation

summary

A text field that contains less than or equal to 255 characters describing the guide.

  • Attributes: None

image

The path to the image introducing the guide. Image is required, so if you do not have an additional primary image, duplicate the first image of the guide.

  • Attributes:
  • mini optional path to a thumbnail of the image no larger than 56x42.
  • thumbnail optional path to a thumbnail of the image no larger than 96x72.
  • standard optional path to a thumbnail of the image no larger than 300x225.
  • medium optional path to a thumbnail of the image no larger than 592x444.
  • large optional path to a thumbnail of the image no larger than 800x600.

author

Author of the guide. In the case of multiple authors, this would be the primary author or maintainer of the guide.

  • Attributes:
  • id optional An id uniquely identifying the user, to be used to tie authors together across documents. (Can be a string or an integer.)

time_required

A human readable description of how long the guide takes. ex: 15 minutes

  • Attributes: None

difficulty

A determination of the difficulty of the guide for your target audience. Please choose from one of these five options:

  • Very easy
  • Easy
  • Moderate
  • Difficult
  • Very difficult
  • Attributes: None

category

The name of the category that this guide belongs to.

  • Attributes: None

introduction

Simplified HTML formatted text introducing the guide. This could describe anything from how to set up for the guide to an introduction of the guides subject matter. There is no length limit, but we suggest limiting this to no more than 2-3 paragraphs.

  • Attributes: None

media

A container for the introduction's media. It can contain one of these: 1-3 images OR a video OR a remote oEmbed object.

  • Attributes:
  • type required The type of media. Valid values: image, video, embed.

image

Image to include with the introduction.

  • Attributes:
  • orderby optional The image order.
  • mini optional Path to a thumbnail of the image no larger than 56x42.
  • thumbnail optional Path to a thumbnail of the image no larger than 96x72.
  • standard optional Path to a thumbnail of the image no larger than 300x225.
  • medium optional Path to a thumbnail of the image no larger than 592x444.
  • large optional Path to a thumbnail of the image no larger than 800x600.

video

Video to include in the introduction.

  • Attributes: none

encoding

Describes the different possible encodings for the video. Different web browsers, mobile devices and operating systems require different formats to play videos. Because of this, there can be 1 to N number of encodings.

  • Attributes:
  • url required Relative location of the video, or a URL if the video is not stored locally
  • width required Video width.
  • height required Video height.
  • codecs required Compression standard used by the video.
  • format required Type of file container that holds one or more codecs. For example - MOV, OGG, AVI, MP4.
  • mime required Internet media type, usually video/{format}. For example - video/ogg, video/mp4, video/webm

poster

Default image for the video. Usually a descriptive image that's shown to display the video, before the video is loaded or played.

  • Attributes:
  • guid optional Unique identifier for the video thumbnail
  • ratio optional Aspect ratio of the thumbnail image. Possible values: ONE_ONE, FOUR_THREE, VARIABLE
  • mini optional Path to the image no larger than 56x42.
  • thumbnail optional Path to the image no larger than 96x72.
  • standard optional Path to the image no larger than 300x225.
  • medium optional Path to the image no larger than 592x444.
  • large optional Path to the image no larger than 800x600.

source

Detailed information about the original video source. This is useful if you have encoded a video from a different codec and format and would like to store information about the original video or access additional information, such as frame_rate or audio_codec which would stay the same between different encodings. This element is flexible, meaning it can include any attributes in addition to the ones described below.

  • Attributes:
  • duration_in_ms optional
  • audio_bitrate_in_kbps optional
  • audio_sample_rate optional
  • video_bitrate_in_kbps optional
  • total_bitrate_in_kbps optional
  • audio_sample_rate optional
  • video_codec optional
  • audio_codec optional
  • frame_rate optional
  • format optional
  • channels optional
  • file_size_in_bytes optional
  • width optional
  • height optional
  • ...

embed

Remote embed to include with the introduction.

  • Attributes:
  • type required The resource type. Valid values are [photo, video, link, rich]. Visit the section on these types in the oEmbed spec to learn more.
  • version required The oEmbed version number. This must be 1.0.
  • html optional The body of the embed object, could be an iframe embedded content or a block of html depending on the type.
  • height optional The height of the embedded object.
  • width optional The width of the embedded object.
  • title optional A text title, describing the resource.
  • author_name optional The name of the author/owner of the resource.
  • author_url optional A URL for the author/owner of the resource.
  • provider_name optional The name of the resource provider.
  • provider_url optional The url of the resource provider.
  • cache_age optional The suggested cache lifetime for this resource, in seconds. Consumers may choose to use this value or not.
  • thumbnail_url optional A URL to a thumbnail image representing the resource. The thumbnail must respect any maxwidth and maxheight parameters. If this parameter is present, thumbnail_width and thumbnail_height must also be present.
  • thumbnail_width optional The width of the optional thumbnail. If this parameter is present, thumbnail_url and thumbnail_height must also be present.
  • thumbnail_height optional The height of the optional thumbnail. If this parameter is present, thumbnail_url and thumbnail_width must also be present.

tools

  • Attributes: None

tool

A required or suggested tool or implement. Use a name common to all of your guides and specify variations using the type attribute.

  • Attributes:
  • name required Tool name.
  • type optional The type of tool. Specifying type can be a useful way of consolidating tool names, for example an 8mm socket could be specified as name: socket, type: 8mm.
  • quantity optional Integer quantity of tool required. If omitted, this is assumed to be 1.
  • notes optional Information specific to using this tool for this guide.
  • thumbnail optional Path to an image to go along with the tool.
  • url optional A URL for an external reference describing the tool.
  • sku optional The manufacturer SKU / part number.

external_sources

A list of all the sources for aquiring this tool.

  • Attributes: None

external_source

External source used for sourcing and aquiring this tool. Could be an e-commerce site, brick and mortar store, guide or full oManual.

  • Attributes:
  • id optional String identifier for the tool at the external source. If the external source is a guide, the id would be the guide name.
  • url optional Path to an external site that sells or distributes this tool. Alternatively, it could be a relative path to a different guide that produces this tool.
  • notes optional Any important information about this source. For example, if the source is notorious for slow shipping times or poor quality, this would be the place to note that.

parts

  • Attributes: None

part

A part, material, or ingredient used in the guide. Use a name common to all of your guides and specify variations using the type attribute.

  • Attributes:
  • name required Part name
  • sku optional A global string identifier for the part.
  • type optional The type of part. Specifying type can be a useful way of consolidating names, for example a 5Ω resistor could be specified as name: resistor, type: 5Ω.
  • quantity required How many of this part are required.
  • thumbnail optional URI of an image to go along with the part.
  • url optional A URL for a page describing the part.
  • notes optional Information specific to using this part for this guide.

external_sources

A list of all the sources for aquiring this part.

  • Attributes: None

external_source

External source used for sourcing and aquiring this part. Could be an e-commerce site, brick and mortar store, guide or full oManual.

  • Attributes:
  • id optional String identifier for the part at the external source. If the external source is a guide, the id would be the guide name.
  • url optional Path to an external site that sells or distributes this part. Alternatively, it could be a relative path to a different guide that produces this part.
  • notes optional Any important information about this source. For example, if the source is notorious for slow shipping times or poor quality, this would be the place to note that.

flags

  • Attributes: None

flag

A flag or informational note about the guide. The text field contains a full text notice of what this flag means to the user.

  • Attributes:
  • id optional A unique string identifier for the flag.
  • title required A short title for the flag. ex: In Progress
  • image optional URI of an image to go along with the flag, no larger than 44x44.

documents

  • Attributes: None

document

A document attached to the guide. The text for this element should be the filename of the attached document.

  • Attributes:
  • url required Path to the document.

prerequisites

A collection of guides that must be completed prior to starting this guide.

  • Attributes: None

prerequisite

The title of a prerequisite guide. Prerequisite guides should be written such that steps can be inlined directly into this guide. You can see an example of this with the prerequisite implementation on iFixit.

  • Attributes:
  • id required An id for the associated prerequisite guide.
  • locale required The language the guide is written in.
  • path required The path to the prerequisite guide.

steps

Collection of step-by-step instructions.

  • Attributes: None

step

The step. Contains the line, object, and image elements.

  • Attributes:
  • number required The step number starting from 1.
  • title optional The title of the step.

lines

Lines of text belonging to this step. We recommend a step not have more than eight lines, and that each line not exceed 500 characters. It is best to think of each line as a discrete piece of information or instruction.

  • Attributes: None

line

A bullet line of text in the step or paragraph of instructions. Recommended not to exceed 500 characters.

  • Attributes:
  • bullet optional Which color or type of bullet to use. If you specify icon_note, icon_reminder, or icon_caution, the bullet color should default to black. Valid values are:
    • black
    • red
    • orange
    • yellow
    • green
    • blue
    • violet
    • icon_note
    • icon_reminder
    • icon_caution
  • level optional How indented this line is. We recommend that the indentation level is no larger than 3.

media

A container for the step media. Each step can have one of these: 1-3 images OR a video OR a remote oEmbed object.

  • Attributes:
  • type required The type of media. Valid values: image, video, embed.

image

Image to include with this step.

  • Attributes:
  • orderby optional The image order relative to the others. Starts at 1.
  • mini optional Path to the image no larger than 56x42.
  • thumbnail optional Path to the image no larger than 96x72.
  • standard optional Path to the image no larger than 300x225.
  • medium optional Path to the image no larger than 592x444.
  • large optional Path to the image no larger than 800x600.

video

Video to include with this step.

  • Attributes: none

encoding

Describes the different possible encodings for the video. Different web browsers, mobile devices and operating systems require different formats to play videos. Because of this, there can be 1 to N number of encodings.

  • Attributes:
  • url required Relative location of the video, or a URL if the video is not stored locally.
  • width required Video width.
  • height required Video height.
  • codecs required Compression standard used by the video.
  • format required Type of file container that holds one or more codecs. For example - MOV, OGG, AVI, MP4.
  • mime required Internet media type, usually video/{format}. For example - video/ogg, video/mp4, video/webm./

poster

Default image for the video. Usually a descriptive image that's shown to display the video, before the video is loaded or played.

  • Attributes:
  • guid optional Unique identifier for the video thumbnail
  • ratio optional Aspect ratio of the thumbnail image. Possible values: ONE_ONE, FOUR_THREE, VARIABLE
  • mini optional Path to the image no larger than 56x42.
  • thumbnail optional Path to the image no larger than 96x72.
  • standard optional Path to the image no larger than 300x225.
  • medium optional Path to the image no larger than 592x444.
  • large optional Path to the image no larger than 800x600.

source

Detailed information about the original video source. This is useful if you have encoded a video from a different codec and format and would like to store information about the original video or access additional information, such as frame_rate or audio_codec which would stay the same between different encodings. This element is flexible, meaning it can include any attributes in addition to the ones described below.

  • Attributes:
  • duration_in_ms optional
  • audio_bitrate_in_kbps optional
  • audio_sample_rate optional
  • video_bitrate_in_kbps optional
  • total_bitrate_in_kbps optional
  • audio_sample_rate optional
  • video_codec optional
  • audio_codec optional
  • frame_rate optional
  • format optional
  • channels optional
  • file_size_in_bytes optional
  • width optional
  • height optional
  • ...

embed

Remote embed to include with this step. Each embed can include the same fields specified by the oEmbed spec.

  • Attributes:
  • type required The resource type. Valid values are [photo, video, link, rich]. Visit the section on these types in the oembed spec to learn more.
  • version required The oEmbed version number. This must be 1.0.
  • html optional The body of the embed object, could be an iframe embeded content or a block of html depending on the type.
  • url optional URL to the source of the embedded media.
  • height optional The height of the embedded object.
  • width optional The width of the embedded object.
  • title optional A text title, describing the resource.
  • author_name optional The name of the author/owner of the resource.
  • author_url optional A URL for the author/owner of the resource.
  • provider_name optional The name of the resource provider.
  • provider_url optional The url of the resource provider.
  • cache_age optional The suggested cache lifetime for this resource, in seconds. Consumers may choose to use this value or not.
  • thumbnail_url optional A URL to a thumbnail image representing the resource. The thumbnail must respect any maxwidth and maxheight parameters. If this parameter is present, thumbnail_width and thumbnail_height must also be present.
  • thumbnail_width optional The width of the optional thumbnail. If this parameter is present, thumbnail_url and thumbnail_height must also be present.
  • thumbnail_height optional The height of the optional thumbnail. If this parameter is present, thumbnail_url and thumbnail_width must also be present.

conclusion

Simple HTML-formatted text for the conclusion.

  • Attributes: None

Transmission Formats

.oManual File Package Example oManual Package

The .omanual file format is an XML-based file package which can be used to easily package, distribute, view and import your data and referenced media files. These files are compressed and packaged using the .ZIP file format, which is an industry standard for cross-platform data exchange and storage.

File examples and schema definition (XSD) files are available below to validate your own oManual XML documents.

oManual packages must have a file extension of '.omanual' and should be structured as shown below.

ZIP compressed .omanual archive:

API Specification

The API specification is designed to provide a simple way to expose your oManual resources to other services or devices through simple REST API endpoints. API endpoints should be relative to a base server address (eg. http://www.ifixit.com/api).

GET/guides

Returns a list of all guides sorted by guideid.

Query Parameters
guideids — Optional — array

Comma-delimited list of guideids identifying the guides to return.

filter — Optional — enum

Return only guides of the specified type. For example, to get all teardowns, you can query /guides?filter=teardown&limit=10000

order — Optional — enum

Return the guides in ascending or descending alphabetical order.

offset — Optional — integer

The number of guides to skip from the beginning. Range: [0, infinity). Defaults to 0.

limit — Optional — integer

The maximum number of guides to include in the response. Range: [1, 200]. Defaults to 20.

Example Response

GET/guides/{guideid}

Returns a comprehensive list of attributes about a guide.

Query Parameters
excludePrerequisiteSteps — Optional — boolean

If set, the response will not include steps from prerequisite guides. By default prerequisite guide steps are inlined with the current guide's steps.

type — Optional — string

Possible values: JSON or XML.

Example Response

GET/categories

Returns a flat list of the category names on the site.

Query Parameters
offset — Optional — integer

The number of categories to skip from the beginning. Range: [0, infinity). Defaults to 0.

limit — Optional — integer

The maximum number of categories to include in the response. Range: [1, 200]. Defaults to 20.

Example Response

GET/categories/{categoryname}

Returns a comprehensive list of attributes about a category, including the full text of the main category page and a list of all guides. The category name must be URL encoded.

Query Parameters
type — Optional — string

Possible values: JSON or XML.

Example Response

More Information

Simplified HTML

Where specified, formatted text within the standard may use simplified XHTML. The text must validate and should not be escaped via CDATA. Simplified HTML is defined as these HTML tags:

<p><a><strong><em><h1><h2><h3><h4><h5><h6><tt><pre><code><br><ul><li><sub><sup><del><ins><div>

With these attributes:

id, class, href, style, rel, title, target

Allowed Paths

Paths can be either an URI to a web resource or a local path, absolute from the base of the package. Local paths are only allowed for offline packages. Fully qualified URIs are always allowed.

Design Paradigms

Design content for display. Yes, you can stuff really long paragraphs into a single step. But it won't look good!

Make life easy for programmers. The most efficient file package will only have a single copy of each image, but providing urls to pre-rendered thumbnails makes designing mobile applications fast.