Newzbin Specification Mirror and DTD Download; Newzbin is Dead - Long live the NZB...

// 25th May '10 Newzbin Specification Mirror and DTD Download; Newzbin is Dead - Long live the NZB...
Disclaimer

Original specification released by Newzbin Ltd

As we all know, Newzbin.com is no longer - and that unfortunately means that the NZB specification no longer has a home. Until a time when it can have a permanent home, we have the cached specification in this post and also a hosted version of the DTD.

The NZB specification was released with the statement "This is an open standard, which anyone can use." but without an actual license of any kind. As such, we are hosting the specification here under Fair Use laws (it is a widely-available open format) until someone challenges otherwise.

If you feel you own the rights to hosting the specification, please get in touch but until then - the NZB format needs a home and we're willing to provide it.

The Spec

NZB (Message-ID List) File Specification

This is a direct copy & paste from the original hosted on docs.newzbin.com.

Here follows a sample NZB for a single small file:

<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE nzb PUBLIC "-//newzBin//DTD NZB 1.1//EN" "http://www.newzbin.com/DTD/nzb/nzb-1.1.dtd">
<nzb xmlns="http://www.newzbin.com/DTD/2003/nzb">
 <head>
   <meta type="title">Your File!</meta>
   <meta type="tag">Example</meta>
 </head>
 <file poster="Joe Bloggs &amp;lt;[email protected]&amp;gt;" date="1071674882" subject="Here's your file!  abc-mr2a.r01 (1/2)">
   <groups>
     <group>alt.binaries.newzbin</group>
     <group>alt.binaries.mojo</group>
   </groups>
   <segments>
     <segment bytes="102394" number="1">[email protected]</segment>
     <segment bytes="4501" number="2">[email protected]</segment>
   </segments>
 </file>
</nzb>

This example is for one file, consisting of two segments, which are 102,394 bytes and 4,501 bytes. The file is posted into two groups, alt.binaries.newzbin and alt.binaries.mojo; it was posted by Joe Bloggs, at unixtime 1071674882. The subject is slightly munged; the segment counter always starts at 1; but you can see it has 2 segments; confirmed by the segments tags below.

This is a fully populated nzb file, all the tags and attributes you can expect to see are there, but clients are expected to cope should more be added.

Since this is an XML format, clients are encouraged to use an XML parser to process it; minor changes to the nzb files we generate such as with attribute ordering, indentation, and even new tags and attributes must be taken into account. XML PI's and CDATA sections are not expected to be used, so clients should be free to cut some corners using lightweight parsers.

We will, where possible, avoid changes which may break clients; even those which use simple pattern matchers. Significant changes to the format are unlikely at this point, but users of the format should try not to get too complacent.

XML Tag breakdown

The tags, one by one.

<nzb>..</nzb>

  • Description - Root element for the file.
  • Attributes - None
  • Body - None (Placeholder)
  • Child - <file>

<head>..</head>

  • Description - Contains all metadata relating to contents of NZB
  • Attributes - None
  • Body - None
  • Children - <meta>

<meta>..</meta>

  • Description - Creator-definable metadata for the contents of the NZB (e.g. title)
  • Attributes:
    1. type string - Identifier for the metadata content
  • Body - string - The metadata content corresponding to the given type
  • Children - None

<file>..</file>

  • Description - Represents a list of messageids that make up a file.
  • Attributes:

    1. poster string - Copy of the From: field from the article header.
    2. date int - Unixtime representation of the date the server saw this article. This is not completely reliable; timezones can break this value, and incorrectly configured news servers will make it almost useless.
    3. subject string - A slightly munged copy of the article's subject. The segment counter (xx/yy) usually found at the end, is replaced with (1/yy). You can use the yy to confirm all segments are present.
  • Body - None (Placeholder)

  • Child - <groups>, <segments>

<groups>..</groups>

  • Description - Placeholder element for a list of groups that reference the file.
  • Attributes - None
  • Body - None (Placeholder)
  • Child - <group>

<group>..</group>

  • Description - One element represents a group, multiple may be used.
  • Attributes - None
  • Body - string - The name of the group (e.g. alt.binaries.newzbin)
  • Child - None

<segments>..</segments>

  • Description - Placeholder element for a list of segments that make up a file.
  • Attributes - None
  • Body - None (Placeholder)
  • Child - <segment>

<segment>..</segment>

  • Description - One part segment of a file.
  • Attributes:
    1. bytes int - Size of the article, in bytes, as a number, with no comma separation.
    2. number int - Segment number of the article, gleaned by parsing (yy/zz)
  • Body - string - The Message-ID of this article, without the surrounding < and > (e.g. [email protected])
  • Child - None
Metadata

Metadata Defined Types

The meta tag (as a child of the head tag), added in NZB 1.1, is designed to allow posters to include arbitrary data in any NZB file, which decoders might find useful. It's a very simple key-value system, where the key is the 'type' attribute.

In order to create some consistency, we define the following types; if you'd like one added, let us know so others will know of it's existence and may choose to use it. As per usual XML, these types are case sensitive so take care.

  • title - a human-readable identifiable title for the contents of the NZB, ie the body of a metadata tag with the title attribute could be "Ubuntu Linux 9.10 64bit Desktop CD"
  • password - if any password is required for the contents of the NZB, it can be specified in a password meta-tag. If there are multiple passwords, this tag could simply be specified more than once and they can all be tried. If it becomes a common requirement we may develop a way to associate a password tag (or indeed any meta tag) with a specific file block.

If you'd like to create your own private type which will never clash with any that we define, prefix it with X- as per HTTP.. ie, X-Some-Private-Type

The DTD

The NZB Document Type Definition

We have re-hosted the Document Type Definition at the link below. Please note this is the original DTD and still contains references to Newzbin.com.

http://www.usenetshack.com/media/docs/DTD/nzb/nzb-1.1.dtd

djm posted by djm
This entry was posted in Informative and tagged nzb-spec, nzbs. Leave a comment. Header image by functoruser

2 Comments

  1. Posted Oct 28th, 2010 at 08:10 a.m.

    last few days our class held a similar talk about this topic and you illustrate something we have not covered yet, appreciate that.

    • Kris
    | Link to comment
  2. Posted May 9th, 2011 at 20:05 p.m.

    No flying from fate.

    | Link to comment

Comments are now closed.